Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How to Debug Workflows

This guide covers debugging and troubleshooting methods for Juglans workflows.

juglans check – Syntax Validation

juglans check validates file syntax without executing anything, similar to cargo check:

# Check all files in the current directory
juglans check

# Check a specific directory
juglans check ./src/

# Check a single file
juglans check src/main.jg

# Show all warnings
juglans check --all

# JSON output (suitable for CI)
juglans check --format json

An exit code of 0 means validation passed; 1 means there are syntax errors.

–verbose Mode

Add --verbose (or -v) to see detailed execution logs:

juglans src/main.jg --verbose

Output includes:

[DEBUG] Loading workflow: main.jg
[DEBUG] Parsed 5 nodes, 4 edges
[INFO]  [init] Starting...
[DEBUG] [init] Output: null
[INFO]  [chat] Calling agent: assistant
[DEBUG] [chat] Request: {"message": "..."}
[INFO]  [chat] Response received (234 tokens)

You can also set the log level via an environment variable:

RUST_LOG=debug juglans src/main.jg
# Scope to a single module:
RUST_LOG=juglans::runtime::python=debug juglans src/main.jg

juglans doctest – Validate Doc Code Blocks

juglans doctest extracts all ```juglans code blocks from Markdown files and validates their syntax through GraphParser::parse().

# Validate a single file
juglans doctest docs/guide/concepts.md

# Validate an entire directory
juglans doctest docs/

# JSON output
juglans doctest docs/ --format json

Code blocks that should not be validated can be marked with ignore:

```juglans,ignore
[broken]: this_is_intentionally_invalid
```

Common Errors

#ErrorCauseSolution
1Duplicate parameter 'X' in node [Y]Two parameters in the same node share a nameRename one (the parser rejects duplicate keys at parse time)
2Graph Error: Pending edge references undefined node 'X'An edge references a node that has not been definedCheck the node name spelling; make sure nodes are defined before edges
3Node 'X' is not reachable from entry node (W002)A node has no path from the entry nodeConnect the node to the graph or remove it
4No API-key providedNo LLM provider configured for chat()Set OPENAI_API_KEY/ANTHROPIC_API_KEY/etc., or define [ai.providers] in juglans.toml
5Agent not found: XThe agent slug does not existCheck the spelling and ensure the corresponding file is imported via libs:
6Tool not found: XAn unregistered tool was calledVerify the tool name is a builtin or that the MCP server is configured
7Cycle detected involving node 'X'. Workflows must be acyclic (DAG). (E002)The graph contains a cycleReview the edge definitions; DAGs do not allow cycles (use while/foreach instead)
8Parse error at line NDSL syntax errorCheck the syntax near that line: bracket matching, quote closure, parameter format
9Variable not found: XA context variable was not setEnsure the variable is set via assignment syntax before it is used
10TimeoutTool execution timed outCheck the network connection or increase the timeout configuration

Debugging Tips

Insert Checkpoints with print()

Insert print() nodes at key positions to inspect intermediate state:

[step1]: data = input.items
[debug1]: print(message="After step1, data = " + json(data))
[step2]: chat(agent="processor", message=json(data))
[debug2]: print(message="After step2, output = " + json(output))
[done]: notify(status="complete")

[step1] -> [debug1] -> [step2] -> [debug2] -> [done]

Save Intermediate State with Assignment

Use assignment syntax to save intermediate results so they can be referenced by later nodes or error paths:

[fetch]: fetch_url(url=input.url)
[save_raw]: raw_response = output
[process]: chat(agent="parser", message=output)
[save_parsed]: parsed = output
[handle_error]: print(message="Failed. Raw response: " + json(raw_response))
[done]: print(message="Result: " + json(parsed))

[fetch] -> [save_raw] -> [process] -> [save_parsed] -> [done]
[process] on error -> [handle_error]

Dry-run Mode

Use --dry-run to parse without executing, quickly verifying the structure:

juglans src/main.jg --dry-run

Isolate Problem Nodes

When a workflow is long, create a minimal test file to test the problematic node in isolation:

# Render a single Prompt
juglans src/prompts/my-prompt.jgx --input '{"name": "Alice"}'

# Test a minimal workflow with an inline agent
juglans test-agent.jg --input '{"message": "test input"}'

Check Configuration

Verify that the current configuration is correct:

# View account and configuration info
juglans whoami --verbose

Next Steps