Troubleshooting

Installation

Node.js version mismatch

Symptom: rf crashes on startup or shows SyntaxError: Unexpected token.

Cause: Radhflow requires Node.js 20 or later. Older versions lack required language features.

Fix:

node --version

If the version is below 20, upgrade:

# Using nvm
nvm install 20
nvm use 20

# Or download from https://nodejs.org

Docker not running

Symptom: rf run fails with Cannot connect to the Docker daemon when running CLI nodes.

Cause: Docker Desktop or the Docker daemon is not running. CLI nodes need Docker for sandboxed execution.

Fix: Start Docker:

# Linux
sudo systemctl start docker

# macOS / Windows
# Open Docker Desktop

Tip

Docker is only required for sandboxed CLI nodes. Basic pipelines using built-in data operations (filter, map, SQL queries) run without Docker.

Permission errors on global install

Symptom: npm install -g radhflow fails with EACCES: permission denied.

Cause: Your global npm directory requires elevated permissions.

Fix: Either fix npm permissions or use npx:

# Option 1: Use npx instead of global install
npx radhflow init my-pipeline

# Option 2: Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g radhflow

---

Pipeline Errors

Schema validation failure

Symptom: rf validate or rf run fails with Schema mismatch or Type error on edge.

Cause: An input port expects a different data type or schema than what the connected output port produces.

Fix: Check the types on both sides of the edge:

flow.yaml

# Output produces a Table
read-data:
  outputs:
    results: { type: Table }

# Input expects a Table — this works
process:
  inputs:
    data: { type: Table, from: ref(read-data.results) }

# Input expects a Record — this fails
process:
  inputs:
    data: { type: Record, from: ref(read-data.results) }

Run rf validate to see all schema errors before executing.

Missing node dependency

Symptom: rf run fails with Unknown node reference or Cannot resolve ref(...).

Cause: A ref() points to a node or port that does not exist in flow.yaml.

Fix: Verify the node ID and port name in the ref() match exactly:

# Wrong — node ID typo
inputs:
  data: { type: Table, from: ref(read-datas.results) }

# Right
inputs:
  data: { type: Table, from: ref(read-data.results) }

Node IDs and port names are case-sensitive.

Circular edges

Symptom: rf validate fails with Cycle detected in graph.

Cause: Two or more nodes reference each other, creating a loop. Pipelines must be directed acyclic graphs (DAGs).

Fix: Trace the dependency chain and remove the cycle. If node A needs output from node B, and node B needs output from node A, restructure the pipeline — split one of them, or introduce an intermediate node.

---

Runtime Errors

Node execution failure

Symptom: rf run shows [node-id] FAILED with a stack trace or error message.

Cause: The node’s operation encountered an error. Common reasons: missing input files, SQL syntax errors, API authentication failures, or malformed data.

Fix: Read the error message. It tells you which node failed and why.

[score-leads] FAILED: SQL error — column "scroe" not found

In this case, fix the typo in your SQL query (scroe to score).

Caution

When a node fails, downstream nodes are skipped. Fix the failing node first, then re-run the pipeline.

Timeout on long-running nodes

Symptom: rf run hangs or fails with Execution timeout.

Cause: A node is taking longer than the configured timeout (default: 5 minutes).

Fix: Increase the timeout in flow.yaml:

flow.yaml

big-transform:
  type: deterministic
  timeout: 600  # seconds
  op: sql.query
  params:
    query: "SELECT ... FROM large_table ..."

If the node is genuinely slow, consider breaking it into smaller steps.

Data type mismatch at runtime

Symptom: A node produces output but the next node fails with Unexpected data format.

Cause: The actual data does not match the declared schema. For example, a score field declared as number contains string values like "N/A".

Fix: Ensure your source data matches the schema. Add a transform node to clean the data if needed:

clean-scores:
  type: deterministic
  op: sql.query
  params:
    query: "SELECT *, CAST(score AS DOUBLE) AS score FROM raw WHERE score != 'N/A'"

---

CLI Issues

rf run hangs

Symptom: rf run starts but produces no output and does not finish.

Cause: Usually a node waiting for input that never arrives (e.g., an HTTP connector waiting for a response from an unresponsive API).

Fix:

1. Press Ctrl+C to stop the run.
2. Run rf run --verbose to see which node is blocking.
3. Check network connectivity if the node calls an external service.

rf validate reports false positives

Symptom: rf validate reports errors, but rf run works fine.

Cause: This is a bug. Validation should be stricter than execution, not the other way around.

Fix: Open an issue with the output of:

rf validate --verbose
rf --version

rf inspect shows empty output

Symptom: rf inspect runs but shows no nodes or data.

Cause: The pipeline has not been run yet, or flow.yaml has no nodes defined.

Fix:

1. Check that flow.yaml exists and has at least one node.
2. Run the pipeline first: rf run
3. Then inspect: rf inspect

rf inspect shows results from the last run. If there is no run history, there is nothing to inspect.

---

Still stuck?

Open an issue on GitHub with:

• Your flow.yaml (remove any secrets)
• The full error output
• Output of rf --version and node --version