Skip to main content

Reference

Troubleshooting

Common issues and solutions when using DxCore.

Coordinator Connectivity

Agent cannot connect to coordinator

Symptom: Agent exits with a connection error or timeout.

Checks:

  • Verify the coordinator URL is correct and includes the protocol (https://)
  • Run dxcore ci wait -c $URL --timeout 60 to confirm reachability
  • Check that your CI runner has network access to the coordinator (firewalls, VPNs)
  • Verify the bearer token is valid and not expired

ci wait times out

Symptom: dxcore ci wait exits after the timeout period.

Checks:

  • Ensure the coordinator is running and the /api/health endpoint responds
  • Increase the --timeout value if the coordinator takes time to start

WebSocket Failures

Dispatcher disconnects mid-run

Symptom: Dispatcher exits unexpectedly while tasks are still running.

Checks:

  • Check the --timeout flag on the dispatch command (default 900 seconds). Increase it for long-running builds with -T.
  • Look for load balancer or proxy timeout settings that may close idle WebSocket connections
  • Ensure the coordinator has not been shut down or restarted

Agent receives no tasks

Symptom: Agent connects but sits idle without executing any work.

Checks:

  • Verify the agent’s --session-id matches the dispatcher’s session
  • Confirm the --build-system flag matches between dispatcher and agent
  • Check that the task graph was submitted successfully by the dispatcher

Adapter Parsing Errors

Turborepo: “Failed to parse dry-run output”

Checks:

  • Ensure you are running turbo run <task> --dry=json (not --dry=text)
  • Verify Turborepo is installed and turbo.json is valid
  • Pipe the output to a file first and inspect it: turbo run build --dry=json > graph.json

Nx: “Failed to parse graph output”

Checks:

  • Ensure you are piping Nx’s task graph JSON to stdin. The recommended command is nx graph --file=stdout — check the Nx documentation for the correct invocation for your version
  • Verify Nx is installed and nx.json / project.json files are valid

Docker: “Failed to parse bake output”

Checks:

  • Ensure you are running docker buildx bake --print (not docker buildx bake which executes)
  • Verify your docker-bake.hcl or docker-bake.json syntax is correct

Shard Mismatch

Tasks split into unexpected shard count

Symptom: A task is split into more or fewer shards than expected.

Checks:

  • Run dxcore config to see resolved shard configuration
  • Check that dxcore.json is in the correct directory (package root, not repo root)
  • Remember priority order: explicit dxcore.json > learned profile > default (1)
  • If learned profiles are overriding your intent, add an explicit dxcore.json

Note

The coordinator logs task scheduling decisions. Check coordinator logs for details on why a specific shard count was chosen.

Session Issues

“Session not found” error

Checks:

  • Ensure ci create-session completed successfully and output a session ID
  • Verify the session ID is passed correctly to all commands (no extra whitespace)
  • Sessions expire after the coordinator restarts — create a new one

Finish step reports failure

Checks:

  • This usually means one or more tasks failed during execution
  • Check the dispatcher output for task-level error details
  • Individual agent logs will show the exact command that failed

Next Steps