Skip to main content

Troubleshooting

Solutions to common issues when running local mode.

Job Format Errors​

"job type cannot be empty"​

Jobs submitted via CLI must use the wrapper format:

name: my-job
type: pipeline
config:
  input: { generate: { interval: 5s, mapping: 'root.hello = "world"' } }
  output: { stdout: {} }

❌ Won't work - missing wrapper:

input:
  generate: { ... }

"pipeline 'input' component is required" / "pipeline 'output' component is required"​

Every job config needs an input and an output. The pipeline section (processors) is optional; add whichever of input or output is missing:

name: my-job
type: pipeline
config:
  input: { generate: { interval: 5s, mapping: 'root.hello = "world"' } }
  output: { stdout: {} }

Connection Issues​

CLI can't connect to the local edge​

The CLI reports could not connect to localhost:9010: connection refused when it targets the wrong port. The default is 9010, not 8080. Pass it explicitly:

export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"
expanso-cli job list --endpoint http://localhost:9010

If you started edge with a custom port:

expanso-edge run --local --api-listen :8080

# In another terminal, from the same folder
export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"
expanso-cli job list --endpoint http://localhost:8080

Port Already in Use​

Error: Error: listen tcp :9010: bind: address already in use

Use a different port:

expanso-edge run --local --api-listen :8080

# In another terminal, from the same folder
export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"
expanso-cli job list --endpoint http://localhost:8080

CLI Can't Find Edge​

Error: could not connect to localhost:9010: connection refused (with the hint: No orchestrator is reachable at localhost:9010. Ensure one is running.)

  1. Verify edge is running—look for the "API server listening" line
  2. Check the port matches your --api-listen setting
  3. Ensure your firewall allows localhost connections

Job Issues​

Job Not Running​

  1. Check job status:

    export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"
    expanso-cli job list --endpoint http://localhost:9010
    expanso-cli job describe <job-id> \
      --endpoint http://localhost:9010

  2. Enable debug logging:

    expanso-edge run --local --log-level debug

Old Jobs Still Appearing​

Clean the state directory:

# Stop edge (Ctrl+C)
rm -rf ./data
expanso-edge run --local

Next Steps​