Troubleshooting

Common errors, what they mean, and how to fix them.

Works in workflow and agent mode.

Dependency errors

Dependency cycle detected

Error: dependency cycle detected (code: DEPENDENCY_CYCLE)

Two or more resources form a circular requires chain (A requires B, B requires A). The engine detects cycles during graph construction and fails before execution.

Fix: break the cycle by removing one of the requires edges. If both resources genuinely need each other's output, merge them into a single resource.

Resource 'x' depends on unknown resource 'y'

Error: resource 'fetchData' depends on unknown resource 'missingResource'

A requires field references an actionId that does not exist in the workflow.

Fix: check for typos in the requires list, or add the missing resource. ActionIds are case-sensitive.

Target resource 'x' not found

Error: target resource 'respond' not found

metadata.targetActionId references a resource that does not exist.

Fix: ensure the actionId in targetActionId matches exactly (case-sensitive) one of the resources in the workflow.

Validation errors

Input validation failed

Error: Input validation failed (code: VALIDATION)
Details: [{"field": "email", "message": "required field missing"}]

A validations.check expression evaluated to false.

Fix: check the request input against the check expressions. Use kdeps run --debug to see the evaluated expression values.

Preflight check failed

Error: Preflight check failed: validation expression error: ...

A check expression contains a syntax error or references an undefined variable.

Fix: validate the expression syntax. Common causes:

Unclosed {{ }} braces
Misspelled function names (get not Get, len not length)
Referencing a key that does not exist without a nil check

Expression errors

Expression evaluation failed

Error: Expression evaluation failed (code: EXPRESSION_ERR)

An expression in before:, after:, or validations could not be evaluated.

Common causes:

Type mismatch: get('age') > 'old' (comparing number to string)
Nil access: lower(get('name')) when name is nil - use lower(get('name') ?? '') instead
Undefined function: using a function that does not exist in expr-lang

Missing value in string interpolation

If {{ get('missingKey') }} renders as empty string, the key does not exist in any data source. Use default(get('missingKey'), 'fallback') to provide a default.

LLM / chat errors

Model not found

Error: model 'llama3.2' not found

The configured LLM model is not available on the backend.

Fix:

For the default file backend: check the alias with kdeps llamafile list (e.g. llama3.2:1b), or pass a URL/path to a .llamafile
For Ollama: run ollama pull llama3.2 to download the model
For OpenAI: check the model name (e.g., gpt-4o, not gpt-4)
Verify the --model flag or KDEPS_AGENT_MODEL env var

llamafile will not start (exec format / run-detectors errors)

Llamafiles are portable executables that re-exec themselves via /bin/sh. On some kernels (binfmt_misc misconfiguration, WSL) the trampoline fails.

Fix:

Run it through a shell explicitly: sh ~/.kdeps/models/<model>.llamafile --version
Ensure $HOME is writable (the APE loader extracts to ~/.ape)
Make sure the file is executable: chmod +x ~/.kdeps/models/*.llamafile

Missing API key

Error: authentication required

The LLM backend requires an API key but none was provided.

Fix: set the appropriate environment variable:

OpenAI: OPENAI_API_KEY
Anthropic: ANTHROPIC_API_KEY
Or pass via KDEPS_AGENT_BASE_URL headers

HTTP client errors

Resource execution timed out

Error: Resource execution timed out after 30s (code: TIMEOUT)

The resource's action exceeded its timeout.

Fix: increase the timeout on the resource:

yaml

# resources/example.yaml
component:
  name: http_request
  with:
    url: https://api.example.com/slow
    timeout: 60s  # increase from default 30s

Resource not reachable

Error: connection refused

The target URL is not accepting connections.

Fix:

Verify the URL is correct and the service is running
Check network connectivity from the kdeps host
If the service is behind a VPN or firewall, ensure access is allowed

Python errors

Python script failed

Error: Resource execution failed: python exited with code 1

The Python script returned a non-zero exit code.

Fix: check stderr output. Run the workflow with --debug to see full Python output. Common causes:

Missing Python package (install with pip)
Syntax error in inline script
Python version incompatibility

Exec errors

Command not found

Error: Resource execution failed: exec: "mycommand": executable file not found in $PATH

The shell command is not available on the system.

Fix: install the command or use the full path. Verify the command works in a regular shell first.

Loop errors

Loop exceeded max iterations

Error: loop exceeded maxIterations (1000)

A loop.while condition never became false, and the safety cap stopped execution.

Fix:

Check the while expression - is it ever becoming false?
Increase maxIterations if you genuinely need more iterations
Add an every delay to slow the loop if it is running too fast

Authentication errors

401 Unauthorized

HTTP/1.1 401 Unauthorized

A request to a workflow route (/api/*, etc.) is missing or has the wrong API auth token.

Fix:

bash

export KDEPS_API_AUTH_TOKEN=dev-token
kdeps run workflow.yaml

curl -X POST http://localhost:16395/api/v1/chat \
  -H "Authorization: Bearer $KDEPS_API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"q": "hello"}'

/health is exempt. /_kdeps/* management routes use KDEPS_MANAGEMENT_TOKEN, not KDEPS_API_AUTH_TOKEN. See Security reference.

If the server refuses to start, set KDEPS_API_AUTH_TOKEN or api_auth_token in ~/.kdeps/config.yaml before running kdeps run.

Debugging

Enable debug logging

bash

kdeps run workflow.yaml --debug

Shows detailed execution logs including expression evaluation, dependency resolution, and resource dispatch.

Record a session for a model to debug

--instrument=<name> records any kdeps run - an agent session or kdeps run - into a folder a model can read and fix from. Bare --instrument names it by its start time. Use =: with a space, the name is taken as the path argument.

bash

kdeps --instrument=billing-bug            # agent session, recorded
kdeps run workflow.yaml --instrument=api-500

text

Recording instrumented session billing-bug in /home/me/.kdeps/instrument/billing-bug
...
Instrumented session billing-bug saved in /home/me/.kdeps/instrument/billing-bug
  Give it to a model to debug: kdeps instrument show billing-bug (or read .../session.md)

The terminal looks as usual (the call-chain trace goes to the file, not the screen, unless --debug). The folder holds:

text

~/.kdeps/instrument/billing-bug/
  session.md     # the command, folder, start and end, event counts, and how to read the other two files
  events.ndjson  # one JSON object per line: prompt, model_request, model_response, tool_call, workflow, session_start/_end
  trace.log      # every log line (debug level) and call-chain trace, timestamped

json

{"ts":"2026-10-17T12:18:39Z","kind":"tool_call","called_as":"bash","name":"bash_exec","arguments":"{\"cmd\":\"echo $((6*7))\"}","result":"42","duration_ms":41}
{"ts":"2026-10-17T12:18:40Z","kind":"tool_call","name":"read_file","arguments":"{\"file_path\":\"/nonexistent/x.txt\"}","error":"{\"error\":\"path /nonexistent/x.txt is outside the working directory\"}","duration_ms":0}
{"ts":"2026-10-17T12:18:41Z","kind":"workflow","event":"resource.failed","workflowId":"chatbot","actionId":"llm","detail":"connection refused"}

A model_request holds everything the model was sent; the system prompt and tool list are recorded once and then as {"unchanged_since_request": N} until they change. A string over 64 KiB is cut, saying how much. A session of the same name is replaced.

bash

kdeps instrument list                 # saved sessions, newest first
kdeps instrument show billing-bug     # session.md + events.ndjson, ready to paste or pipe to a model (--trace adds trace.log)
kdeps instrument path billing-bug     # the folder, to point a model's read_file at
kdeps instrument rm billing-bug

Validate workflow without executing

bash

kdeps validate workflow.yaml

Checks the workflow schema, dependency graph, and expression syntax without running any actions.

Troubleshooting ​

Dependency errors ​

Dependency cycle detected ​

Resource 'x' depends on unknown resource 'y' ​

Target resource 'x' not found ​

Validation errors ​

Input validation failed ​

Preflight check failed ​

Expression errors ​

Expression evaluation failed ​

Missing value in string interpolation ​

LLM / chat errors ​

Model not found ​

llamafile will not start (exec format / run-detectors errors) ​

Missing API key ​

HTTP client errors ​

Resource execution timed out ​

Resource not reachable ​

Python errors ​

Python script failed ​

Exec errors ​

Command not found ​

Loop errors ​

Loop exceeded max iterations ​

Authentication errors ​

401 Unauthorized ​

Debugging ​

Enable debug logging ​

Record a session for a model to debug ​

Validate workflow without executing ​

See also ​

Troubleshooting

Dependency errors

Dependency cycle detected

Resource 'x' depends on unknown resource 'y'

Target resource 'x' not found

Validation errors

Input validation failed

Preflight check failed

Expression errors

Expression evaluation failed

Missing value in string interpolation

LLM / chat errors

Model not found

llamafile will not start (exec format / run-detectors errors)

Missing API key

HTTP client errors

Resource execution timed out

Resource not reachable

Python errors

Python script failed

Exec errors

Command not found

Loop errors

Loop exceeded max iterations

Authentication errors

401 Unauthorized

Debugging

Enable debug logging

Record a session for a model to debug

Validate workflow without executing

See also