Skip to main content

​
Installation issues

Refrain requires Node.js 18 or later. Check your version:
node --version
If it’s below 18, update Node.js using nvm, fnm, or download from nodejs.org.
If npm install -g fails with permission errors, either:
  • Use npx @refrainai/cli instead (no global install needed)
  • Fix npm permissions: npm docs
Refrain bundles a Chromium binary automatically. If it’s not found, try reinstalling:
npm install -g @refrainai/cli
If behind a corporate proxy, ensure the proxy allows downloading from Playwright’s CDN.

​
AI provider issues

Ensure the appropriate environment variable is exported for your provider:
# Anthropic (default)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."
See AI Provider Setup for all provider variables.
You’ve hit the provider’s rate limit. Options:
  • Wait and retry — Refrain automatically retries with exponential backoff
  • Use a different model or provider
  • Contact your AI provider to increase limits
Double-check the model ID matches your provider. Common examples:
  • Anthropic: claude-sonnet-4-6
  • OpenAI: gpt-4o
  • Google: gemini-2.5-pro
  • Bedrock: anthropic.claude-sonnet-4-6-v1:0
  • Vertex: claude-sonnet-4-6@20250514

​
Generation issues

  • Press Enter to pause and provide guidance
  • Add more detail to context.md about the target page
  • Try a more specific --goal
  • Increase --max-iterations if the workflow is long
Add navigation hints to context.md:
- After login, go directly to /settings (don't click on the dashboard)
- The export button is under the "Reports" tab, not the "Dashboard" tab
Check the generated report for details on where AI stopped. Common causes:
  • Insufficient context — add more detail to context.md
  • Bot detection — try --stealth mode
  • Complex multi-step workflow — break into smaller goals
Use stealth mode to apply anti-detection patches:
npx @refrainai/cli generate -- \
  --url "https://example.com" --goal "..." --output ./flow.yaml \
  --stealth
Some sites may also require --proxy to route through a residential proxy.

​
Execution issues

The UI may have changed since the runbook was generated. Options:
  1. Run with --self-heal to get AI repair suggestions
  2. Run with --headless false to see what the page looks like
  3. Use --screenshots to capture the page state at each step
Check the variable’s source type:
  • prompt — asks interactively at the CLI
  • env — reads from environment variables (ensure they’re exported)
  • context — requires a --context file
  • fixed — the value should be in the runbook definition
  • secrets — requires a --secrets file
The page may be slow to load. Options:
  • Increase --step-delay to give pages more time between steps
  • Add a wait step in the runbook before the failing step
  • Check network connectivity to the target site
Ensure --output-dir is set:
npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --output-dir ./downloads
The directory is created automatically if it doesn’t exist.

​
Approval & notification issues

The Interactivity Request URL is invalid or unreachable. Verify the URL in your Slack App’s Interactivity settings. See Approval & Notifications for setup details.
The callback is not reaching the executor. Verify that the callback endpoint is accessible from the internet and the Slack App’s Request URL is correctly configured.
The bot hasn’t been invited to the Slack channel. Run /invite @your-bot-name in the target channel.

​
Debugging tools

When troubleshooting, these flags are your best friends:
FlagWhat it does
--headless falseShow the browser window to see what’s happening
--screenshots <dir>Save a screenshot after each step
--reportGenerate a detailed Markdown execution report
--debugPrint debug output to the console
npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --headless false \
  --screenshots ./debug-screenshots \
  --report \
  --debug

​
Getting help