Troubleshooting

Common issues and their solutions.

Diagnostic Commands

Start with these:

# Full system check
prompts-gpt doctor

# Check provider availability
prompts-gpt providers

# Check workspace status
prompts-gpt status

# Validate config and prompts
prompts-gpt validate

Common Issues

Provider Not Found

Symptom: Error: No provider available

Solutions:

``bash which codex which claude which cursor ``

1. Check if the provider CLI is installed:

``bash npm install -g @openai/codex npm install -g @anthropic-ai/claude-code ``

1. Install the missing provider:

``bash echo $PATH prompts-gpt doctor ``

1. Check your PATH:

Authentication Failed

Symptom: Error: AUTH_ERROR — Invalid or missing token

Solutions:

``bash ls -la .prompts-gpt/.credentials.json ``

1. Check credentials file exists:

``bash prompts-gpt init --token pgpt_your_token ``

1. Re-initialize:

``bash echo $PROMPTS_GPT_TOKEN ``

1. Check environment variable:

Sweep Lock Conflict

Symptom: Error: Sweep lock already held

Solutions:

``bash ps aux | grep prompts-gpt ``

1. Check if another sweep is running:

``bash prompts-gpt sweep --force-unlock ``

1. Force-release stale lock:

``typescript import { forceReleaseSweepLock } from "prompts-gpt"; await forceReleaseSweepLock(promptFile, cwd); ``

1. Programmatic force-release:

Timeout Errors

Symptom: Error: Execution timed out

Solutions:

``bash prompts-gpt run task.md --timeout 1800 ``

1. Increase timeout:

``json { "timeoutSeconds": 1800 } ``

1. Set in config:

``bash prompts-gpt sweep audit.md -n 3 --timeout 1800 ``

1. For sweeps, timeout applies per-iteration:

Config File Issues

Symptom: Error: Invalid config

Solutions:

``bash prompts-gpt validate ``

1. Validate config:

``bash prompts-gpt setup ``

1. Regenerate config:

``bash node -e "JSON.parse(require('fs').readFileSync('.prompts-gpt/config.json','utf8'))" ``

1. Check JSON syntax:

No Prompts Found

Symptom: No prompt files found

Solutions:

``bash prompts-gpt sync ``

1. Sync from API:

``bash prompts-gpt generate --goal "Review code for security" ``

1. Generate a prompt:

``bash ls .prompts-gpt/ ``

1. Check prompt directory:

API Connection Errors

Symptom: Error: NETWORK_ERROR

Solutions:

``bash echo $PROMPTS_GPT_API_URL ``

1. Check internet connectivity
2. Check API URL:
3. For self-hosted: verify the server is running

Permission Errors on Credentials

Symptom: Warning: Credentials file has overly permissive permissions

Solution:

chmod 600 .prompts-gpt/.credentials.json

The SDK auto-fixes this on load, but the warning indicates the file was created or modified with incorrect permissions.

Interactive Mode Not Working

Symptom: Prompts don't appear, command exits immediately

Causes:

• Running in CI (stdin is not a TTY)
• CI environment variable is set
• Piped input

Solution: Provide all arguments explicitly:

prompts-gpt run .prompts-gpt/review.md --provider codex --model gpt-5.5

Debug Mode

Enable detailed logging:

DEBUG=prompts-gpt:* prompts-gpt run review.md --provider codex

This logs:

• Provider detection details
• Command construction
• Process execution
• Output parsing
• Artifact writing

Getting Help

1. Run prompts-gpt --help or prompts-gpt <command> --help
2. Check the documentation
3. Run prompts-gpt doctor and share the output

See Also

• Doctor CLI
• Status CLI
• Validate CLI