Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Troubleshooting

​
”step type not yet implemented”

You used a step type that Replay does not recognise. Valid types: http, db, shell, print, loop, call, if. 
# Wrong
type: grpc

# Correct
type: http

​
”unknown field” during parsing

The YAML parser rejects keys that are not part of the workflow schema. This catches typos early. 
# Wrong — "methd" instead of "method"
request:
  methd: GET

# Correct
request:
  method: GET

​
”no command provided” for shell step

A shell step must include either command or commands: 
# Fix
- name: example
  type: shell
  command: "echo hello"

​
“postgres DSN is not configured”

You need to set the PostgreSQL DSN. Either in the workflow config, the config file, or via environment variable: 
config:
  postgres:
    dsn: postgres://user:pass@localhost:5433/mydb
Or in replay.yaml: 
config:
  postgres:
    dsn: "{{ POSTGRES_DSN }}"

export POSTGRES_DSN="postgres://user:pass@localhost:5433/mydb"
replay run workflow.yaml

​
“redis requires a command”

Redis steps need a command array: 
- name: get-value
  type: db
  engine: redis
  command: ["GET", "mykey"]

​
“invalid JSONPath” errors

JSONPath syntax can be tricky. Common mistakes:
WrongRight
data[0]$.data[0] or $[0]
data..items$..items
data.*.name$.data[*].name
data.items.0$.data.items[0]
Enable debug mode to see the full response: 
config:
  http:
    debug: true

​
“command and commands are mutually exclusive”

Use either command (single) or commands (multiple), not both: 
# Wrong
- name: example
  type: shell
  command: "echo hello"
  commands:
    - "echo world"

# Correct — pick one
- name: example
  type: shell
  commands:
    - "echo hello"
    - "echo world"

​
“query and command are mutually exclusive”

DB steps can have a query (PostgreSQL) or command (Redis), but not both: 
# Wrong
- name: example
  type: db
  query: SELECT 1
  command: ["GET", "key"]

​
“variable is required but not set”

The workflow’s config.validate section declares a required variable that was not provided. Set it via config.vars, an environment variable, or a config profile.

​
”variable is not a list” in loop

The foreach field references a variable that exists but is not an array: 
# Wrong — "name" is a string
extract:
  name: $.data.name
steps:
  - name: loop
    type: loop
    foreach: name, item

# Correct — "items" is an array
extract:
  items: $.data.items
steps:
  - name: loop
    type: loop
    foreach: items, item

​
Shell Command Timeout

If a command times out, increase the timeout value: 
- name: long-task
  type: shell
  command: "slow-operation"
  timeout: "120s"

​
“fork/exec … no such file or directory”

Shell commands run via sh -c. If your system does not have sh (e.g., minimal Docker images), install it or use a distro that includes a shell.

​
Connection Refused for Postgres/Redis

Ensure your database services are running and reachable: 
# Check Postgres
psql postgres://postgres:password@localhost:5433/postgres -c "SELECT 1"

# Check Redis
redis-cli -h localhost -p 6379 ping
Remember that Replay’s Docker Compose uses port 5433 for Postgres.

​
”cycle detected” error

A call step is causing a recursive loop. This happens when a workflow calls itself — directly, through mutual recursion (A → B → A), or inside nested if/loop blocks. Check for: 
# Direct self-call (detected by replay validate)
- name: recurse
  type: call
  file: same-file.yaml    # ← calls the file it lives in

# Mutual recursion (detected at runtime)
# a.yaml calls b.yaml, b.yaml calls a.yaml → cycle at runtime
Fix by removing the cycle or restructuring the composition.

​
”call depth exceeded” error

The call chain is deeper than the --max-call-depth limit (default 100): 
call depth exceeded (10): pipeline.yaml → setup.yaml → seed.yaml
Either increase the limit: 
replay run workflow.yaml --max-call-depth 200
Or simplify the workflow composition to reduce nesting depth.

​
”debug” Output Not Showing

Pass the --debug flag or set config.http.debug: true: 
replay run workflow.yaml --debug

​
Getting Help

  • Open an issue on GitHub
  • Check existing issues for similar problems
  • Include the workflow YAML and full error output when reporting a bug