Troubleshooting
This page covers the most common problems when using Parton.
Install problems
parton: command not found
The install directory may not be in your PATH.
A common fix:
export PATH="$HOME/.local/bin:$PATH"
Then restart your shell and try again:
parton version
Permission denied during install
The installer may not have permission to write to the target directory.
Try again and follow the permission prompt, or use a user-writable install path.
Unsupported OS or architecture
Parton currently supports:
- macOS Apple Silicon
- macOS Intel
- Linux x64
Setup problems
Provider CLI not detected
Make sure the provider CLI is installed and available in your shell PATH.
Model list does not load
Possible causes:
- expired provider login
- invalid provider CLI session
- missing API key
- provider outage
Run:
parton doctor
API key invalid
Reconfigure setup or export the correct key, then run:
parton doctor
Run problems
Clarification keeps asking questions
Your prompt may still be too ambiguous.
Try being more specific.
Instead of:
parton run "create app"
say:
parton run "create a Next.js TypeScript todo app with local state and no auth"
Planning failed
Check:
- setup is complete
- provider is reachable
- clarification completed
- the prompt is specific enough
No valid worker output
This usually means the provider returned malformed output or the protocol enforcement rejected it.
Check:
- lane logs
- worker output logs
- provider status
Provider problems
HTTP 500 / provider outage
Parton treats transient provider failures as retryable.
It retries with backoff before pausing.
Rate limit
Parton may retry or pause depending on the failure type.
No credits / quota exhausted
Parton can pause the run instead of losing progress.
Resume later with:
parton resume <run_id>
Internet drop
Transient network failures are retried first.
If they continue, the run may pause safely.
Validation and repair problems
Repair escalated
This means Parton tried to repair validation failures but could not converge.
You should open the review page, inspect the diff, and decide what to do next.
Final validation failed
Check:
- validation logs
- repair artifacts
- review page
- final summary
Recovery and resume
Resume a paused run
parton resume <run_id>
Use this after:
- provider outage
- network recovery
- quota reset
- local interruption
Crash or interruption
Parton stores run artifacts and state so that failures are inspectable and some runs can be resumed.
Where to look when debugging
Useful places:
- run summary
- timeline
- validation logs
- repair logs
- lane logs
- worker input/output artifacts
You can also inspect:
parton logs <run_id>
Good debugging workflow
- Run
parton doctor - Inspect the CLI output
- Open the review page
- Check validation and repair logs
- Resume if the run was paused