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:

Wrong	Right
`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

Overview

Guides

CLI Reference

Configuration