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: { ... }
  pipeline:
    processors: []
  output: { ... }

❌ Won't work - missing wrapper:

input:
  generate: { ... }

"pipeline component is required"​

Include the pipeline section even if empty:

name: my-job
type: pipeline
config:
  input: { ... }
  pipeline:
    processors: []  # Required even if no processors
  output: { ... }

Connection Issues​

"failed to connect to edge"​

The CLI is trying to connect to the wrong port. The default is 9010, not 8080.

export EXPANSO_CLI_ENDPOINT=http://localhost:9010

If you started edge with a custom port:

expanso-edge run --local --api-listen :8080
export EXPANSO_CLI_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
export EXPANSO_CLI_ENDPOINT=http://localhost:8080

CLI Can't Find Edge​

Error: no Expanso orchestrator found at localhost:9010

  1. Verify edge is running—look for the "API server starting" message
  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:

    expanso-cli job list
    expanso-cli job describe <job-id>

  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​