Troubleshooting

This page collects the most common problems encountered while using the C⏚ toolchain. If you're seeing something that isn't listed here, file an issue at Neosyn-Logic/cg-compiler.

Quick diagnosis

Three commands that answer most "what's broken?" questions:

# Is the VS Code extension installed and which version?
code --list-extensions --show-versions | grep neosyn
 
# Is the bundled language-server JAR where we expect it?
ls -la ~/.vscode/extensions/neosyn.neosyn-cg-*/server/cg-language-server.jar
 
# What did the language server log last?
tail -50 ~/neosyn-ir-debug.log

If the third command shows nothing, the server may not have logged yet - see Debug logging further down.

Common compile errors

The language server reports errors through the standard LSP diagnostics channel. VS Code surfaces them in the Problems panel and inline in the editor. The CLI prints them to stderr in a file:line:col: severity: message format.

The six errors below cover most first-week beginner pain.

Unresolved import

Counter_test.cg:3:1: error: The import 'com.example.Counter' could
  not be resolved.

The import path must match the package declared at the top of the target file and the file's location on disk. A file declaring package com.example; must live at <src-root>/com/example/, and its base name must match the entity name (e.g. Counter.cg for task Counter).

Fix: confirm the package matches the folder path, the file name matches the entity, and the import string is the fully-qualified entity name. See Install for project layout.

Type mismatch

Counter.cg:14:9: error: Cannot assign 'u8' to 'u4'.

C⏚ does not narrow integers implicitly. Assigning a wider value into a narrower variable, or mixing signed (i8) and unsigned (u8), produces this error.

Fix: widen the destination, cast (narrow = (u4) wide), or mask the source down to the bits you want (narrow = (u4)(wide & 0xF)).

There is no Verilog-style range slice: wide[3:0] does not parse. Indexing a scalar gives you one bit as a bool (wide[3]); for a range, shift and mask. The full unification rules live in Declarations, and the bit-access forms in Expressions.

Port written twice in the same cycle

Counter.cg:22:5: error: Port 'count' is written more than once in
  the same cycle on this path.

A task may write a given output port at most once per cycle. The compiler flags any control-flow path that reaches two writes without a cycle break in between.

Fix: either guard the writes with if/else so only one fires per cycle, or insert an explicit cycle break (idle(1);, or split the work into two loop() iterations). See Tasks → Cycle breaks.

Two writers to the same port

TopNet.cg:11:3: error: Port 'TopNet.hash' has 2 writers; expected
  exactly 1.

Every writable port (a network output, or an instance input) accepts exactly one writer. Two instance.writes(hash) calls, or a .writes(...) plus a direct assignment, both trip this.

Fix: pick one writer. If you need to merge values from two sources, add a multiplexer task or a FIFO between them. The single-writer rule is part of the language's determinism guarantee; see Concepts → Deterministic by construction.

Unconnected port at synthesis time

HDL generation: warning: Port 'inst1.padded_msg' is unconnected;
  emitting tie-off.
HDL generation: error: Required output 'TopNet.hash' has no driver.

HDL generation reports any input port left dangling and refuses to emit a network whose declared outputs are not driven. The bytecode simulator is more permissive and may run regardless.

Fix: add the missing .reads(...) or .writes(...) call. If a port is intentionally unused, drive it with a constant from an inner task. See Networks → Connecting ports.

Declaration below the first entity

Fir.cg:9: Syntax error: a file-scope declaration must come BEFORE
  the first `task`, `network` or `bundle` - move it up, just after
  the imports.
Fir.cg:6: TAPS cannot be resolved

const, typedef, struct and enum can be written at file scope, but only above the first entity. Written below one they do not parse, and every use of the name then reports as unresolved.

Fix: move the declaration up, directly under the imports. If the error names a token that is already inside an entity, that is not the real problem. The parser was derailed earlier, so fix the first diagnostic and re-check. See Bundles → Declarations at file scope.

Warnings worth acting on

A warning does not stop the build. The command still finishes and still prints Success!. Some of these warnings are real objections to your design, so read them rather than scrolling past:

[neosyn] warning: BoolEq.cg:5: The operator == is undefined for
  the argument types bool and u1
Success! Generated 6 files.

Two you are most likely to hit:

• The operator == is undefined for the argument types bool and u1 - you wrote flag == 1. It compiles and simulates correctly, but the idiomatic spelling is if (flag), or flag == true. On releases before v2.10.0 this crashed HDL generation and dropped the entity from the output.
• missing test values for port "y" - your test block drives inputs but never checks that output, so the run proves nothing. See Properties → List the outputs.

Simulation issues

Simulation hangs and never finishes

The bytecode simulator stops when the network's test property is satisfied. If you forget to declare one, the sim runs until the default cycle cap (maxCycles, 10 000 by default).

The canonical pattern is a monitor task with a bool finished state variable:

properties {
  test: { terminate: "monitor.finished" }
}
 
monitor = new task {
  bool finished;
  void setup() {
    // … checks …
    finished = true;
  }
};

See Bytecode simulator → Test networks.

"Wrong entity" or "no main method"

Symptom: the sim runs and immediately exits, or it picks the wrong top-level entity (e.g. the network instead of the test network).

The server picks a top automatically using a priority list (see Language server → neosyn/simulate. If the heuristic guesses wrong:

• From the CLI: java -jar cg-language-server.jar simulate file.cg --entity MyTestNet.
• From VS Code: open the file containing the test network before running Fast Sim. The active editor seeds the heuristic.

NoClassDefFoundError: com/neosyn/runtime/VcdWriter

The simulator's runtime classes are bundled inside the language server JAR. This error means the JAR is missing them - almost always because the extension was sideloaded from an older .vsix or the bundled JAR was overwritten by hand.

Reinstall the latest extension:

code --install-extension neosyn-cg-<version>.vsix --force

Then reload the VS Code window. The next simulate call will use the freshly bundled JAR.

Simulation exits with no output

A sim that "succeeds" but prints nothing usually means the test network never advanced past setup(). Common causes:

• A for loop in monitor.setup() that waits on a port that is never driven.
• A read() on a push port the DUT writes to before the monitor is wired to it - port writes happen one cycle after the value is staged, so the monitor must read on cycle N+1.
• terminate: "monitor.finished" references a state variable that was never set to true.

Open the .vcd at the project root (next to src/) and check whether the monitor ever fired - that will tell you which case you're in.

HDL generation issues

Generated files end up in the wrong directory

The server picks a project root by walking upward from the source file until it finds either a .project marker or a src/ directory. If neither exists, output lands in the workspace root.

Fix: either create a src/ folder and put your .cg files inside, or pass an explicit output directory on the command line:

java -jar cg-language-server.jar generate file.cg --output ./verilog-gen

Inline tasks missing from generated HDL

A network that declares inner = new task { … }; should emit a module for that inline task alongside the network's own module. If a downstream synthesizer reports the module is missing, check that IR was regenerated after the most recent edit - open the source file again to trigger a save-driven regeneration, or run generate-ir from the CLI.

VS Code extension issues

No syntax highlighting or completions

Open the Output panel and switch to the Neosyn C⏚ channel. The most common causes:

Extension installed but commands missing from the palette

Reload the window: Ctrl+Shift+P → Developer: Reload Window. If commands still don't appear, the extension may have failed during activation - check the Output → Neosyn C⏚ channel for a stack trace.

Debug logging

Set NEOSYN_DEBUG=1 before launching the language server:

NEOSYN_DEBUG=1 java -jar cg-language-server.jar

For the VS Code extension, set the environment variable in the terminal you launch code from. Logs append to ~/neosyn-ir-debug.log (no rotation).

Tail the log in another terminal while reproducing the issue:

tail -f ~/neosyn-ir-debug.log

Recovery procedures

Reset the IR cache

If .ir files appear to be stale or corrupted, delete them and let the server regenerate from source:

Warning: this removes generated intermediate files for the selected project tree. It should not remove source .cg files, but do not run it from a broad parent directory unless you mean to clear every nested project as well.

find /path/to/project -name "*.ir" -delete
rm -rf /path/to/project/.ir

Reopen the project (or re-save a .cg file); IR regenerates automatically.

Reset simulation output

Warning: remove only the simulation output directory for the project you are actively debugging.

rm -rf /path/to/project/sim

The next simulation rebuilds bytecode from scratch.

Reinstall the VS Code extension

code --uninstall-extension neosyn.neosyn-cg
code --install-extension neosyn-cg-<version>.vsix --force

Then Developer: Reload Window.

If you installed from the marketplace rather than a local .vsix, replace the second command with:

code --install-extension neosyn.neosyn-cg --force

Getting help

• ~/neosyn-ir-debug.log - the language server's log.
• Output → Neosyn C⏚ in VS Code.
• The downloads portal for the latest release and its changelog.
• Open an issue at Neosyn-Logic/cg-compiler.