> ## 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

> Common issues and solutions when working with Replay.

# 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`.

```yaml theme={null}
# 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.

```yaml theme={null}
# 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`:

```yaml theme={null}
# 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:

```yaml theme={null}
config:
  postgres:
    dsn: postgres://user:pass@localhost:5433/mydb
```

Or in `replay.yaml`:

```yaml theme={null}
config:
  postgres:
    dsn: "{{ POSTGRES_DSN }}"
```

```bash theme={null}
export POSTGRES_DSN="postgres://user:pass@localhost:5433/mydb"
replay run workflow.yaml
```

## "redis requires a command"

Redis steps need a `command` array:

```yaml theme={null}
- 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:

```yaml theme={null}
config:
  http:
    debug: true
```

## "command and commands are mutually exclusive"

Use either `command` (single) or `commands` (multiple), not both:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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:

```yaml theme={null}
- 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:

```bash theme={null}
# 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:

```yaml theme={null}
# 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):

```text theme={null}
call depth exceeded (10): pipeline.yaml → setup.yaml → seed.yaml
```

Either increase the limit:

```bash theme={null}
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`:

```bash theme={null}
replay run workflow.yaml --debug
```

## Getting Help

* Open an issue on [GitHub](https://github.com/tomiwa-a/replay/issues)
* Check existing issues for similar problems
* Include the workflow YAML and full error output when reporting a bug