Troubleshooting

Nothing happened after tick

tick prints why nothing ran. Read the reason line.

Not due: the series is outside its posting window. Run npx vfrey tick --now.
Paused: the series is paused. Resume it on the dashboard, or ask your agent.
A job in progress: the line names a job and its cancel command. If the run was interrupted, the next tick reclaims it once its process is gone. If it does not, cancel the job, then retry it. A run with --about or --script is a one-off and is not blocked by a series job in progress.

npx vfrey desk snapshot --json
npx vfrey desk job cancel --id JOB_ID
npx vfrey desk job retry --id JOB_ID

Skill not found

The agent does not know vfrey. In a project, the skill is already in .claude/skills/vfrey/ and .agents/skills/vfrey/: make sure you started the agent in the project folder, and that the project is trusted if your agent asks. Outside a project, each agent reads skills from its own folder, so installing for the wrong one does nothing. Install the skill for your agent, then start a new session (Gemini CLI: /skills reload).

Agent	Command
Claude Code	`npx @vfrey/vfrey@beta skill install --agent claude`
Codex	`npx @vfrey/vfrey@beta skill install --agent codex`
Grok	`npx @vfrey/vfrey@beta skill install --agent grok`
Cursor	`npx @vfrey/vfrey@beta skill install --agent cursor`
Gemini CLI	`npx @vfrey/vfrey@beta skill install --agent gemini`

Use --agent all to install for every agent, or --force to replace a different copy. Grok shows what it loaded with grok inspect, and Codex lists skills with /skills. See Your agent.

Doctor says the skill is not installed, but I installed it

Doctor looks in every agent’s skills folder and passes when any copy is current. If it fails, the skill is missing or older than the package. Run the Fix: line it prints, for example npx @vfrey/vfrey@beta skill install --agent codex. If you used --dir for another agent, doctor cannot see that folder. See Your agent.

Not in a vfrey project

Not in a vfrey project; using the machine desk ~/.vfrey. Start one: npm create vfrey@beta my-channel

You ran a command that makes or lists videos in a folder that is not inside a project, so it used the machine desk. Commands look for vfrey.json in the current folder and then each parent folder. Either cd into your project, or start one with npm create vfrey@beta my-channel. npx vfrey projects lists the projects on this machine. npx vfrey open outside a project, with no videos on the machine desk, lists them and asks you to cd into one. The line is not printed when DATA_DIR or VFREY_HOME is set, because those choose the data folder.

`npx vfrey` says 404 or not found outside a project

npm error 404 Not Found - GET https://registry.npmjs.org/vfrey - 'vfrey@*' is not in this registry.

The package is @vfrey/vfrey, not vfrey, and a project installs it in its own node_modules. So npx vfrey works inside a project folder and fails in a folder that has no vfrey installed. Do one of these:

Start a project with npm create vfrey@beta my-channel, then run npx vfrey ... inside it.
Run the scoped package from any folder: npx @vfrey/vfrey@beta init.
Install it once with npm i -g @vfrey/vfrey@beta, then run vfrey ... anywhere.

Do not run npm i vfrey: that name is not this package.

The dashboard is already running

npx vfrey open reuses this project’s dashboard and prints its URL, so this is normal. npx vfrey dashboard does the same: when this project’s dashboard is listening, it prints that address and exits 0 instead of starting a second one. To see which projects have a dashboard up, run npx vfrey projects. If the page you reach is for another project, its name (sidebar, or top bar on a narrow window) says so. To stop a dashboard a tick left running, run npx vfrey dashboard stop in that project. Each project has its own dashboard on its own port, so run npx vfrey open from the folder you mean.

The dashboard port is taken

Without --port, the dashboard uses the port it recorded last if that is free, else 4317 (VFREY_DASHBOARD_PORT changes that default), else the first free port above it, trying up to 50. So a busy 4317 is handled for you (with 4317 to 4319 taken, you get 4320), and the first line printed is the real address. npx vfrey open prints the URL too. Force a port with npx vfrey dashboard --port PORT.

`open` says the dashboard did not start

npx vfrey open starts the dashboard in the background and waits for it. If it fails, it prints the last lines of .vfrey/dashboard.log and a Fix: line. Run npx vfrey dashboard in the foreground to see the error.

A symlinked folder

vfrey resolves symlinks, so a folder that is a symlink to a project, or inside one, finds that project. The dashboard check and the machine index use the real path too, so one project is never listed twice. If vfrey still says it is not in a project, run npx vfrey projects to see the real root, and cd there.

The first render is slow

The first render downloads Chrome Headless Shell, about 170 MB, once. Later renders do not. If the download fails, run npx remotion browser ensure, then run tick again.

An engine shows unavailable

npx vfrey engine list gives the reason. vfrey Framey shows unavailable until Chrome Headless Shell is downloaded. Run npx remotion browser ensure, or make one Remotion render. HyperFrames needs the upstream hyperframes CLI. ComfyUI is not wired yet. A job on an unavailable engine ends blocked with a Fix: line. See Engines.

A command or flag is not clear

npx vfrey --help lists the commands. npx vfrey COMMAND --help lists the flags of one.

Doctor reports a problem

Each failed check prints a Fix: line. Apply it, then run doctor again.

npx vfrey doctor

The disk is full

✗ ... the disk is full: this needs about 2.0 GB of free space and N is free on the drive that holds PATH means the render ran out of room. Free space, then run it again. It is safe to delete the vfrey temp folders (vfrey-* in your system temp folder) and old previews and render scratch (.vfrey/preview and .vfrey/public in the project); vfrey rebuilds them. Your finished videos in videos/ are yours: keep them. The readable message replaces the renderer’s raw output; the raw text is in the log.

Publish is skipped

missing_key means no platform key is set. The video stays in your project’s videos/ folder (or ~/.vfrey/renders/ on the machine desk). Add your own keys with the desk verbs. npx vfrey push refuses for now.

A video was rejected or blocked

Read the Check failed: line in the tick summary, or the Checks list on the run page. Each failed check has a Fix: line. rejected means a quality check failed: fix the script, scene, or layout it names and run again. blocked means a compliance check failed, such as a banned claim or a missing disclosure. Blocked jobs are never retried, so change the content. See Quality checks and Disclosure.

The background worker is not making videos

Run npx vfrey service status. It shows whether the service is installed and running, the last cycle, and each project’s last tick and next due time. Read the log with npx vfrey service logs. A project is skipped when it has no due, unpaused series, or when another tick holds its lock (.vfrey/worker.lock). A project whose folder moved shows missing: run a command inside it so the index updates. See Background worker. That is expected for now. Free features never need an account. See Account.

A series makes videos but nothing uploads

A new series is in dry-run. It records a dry-run publication and uploads nothing, and the tick summary says Not uploaded to youtube: this series is not live yet (it says Dry run (--dry-run) only when you pass the flag). The Publications page shows the badge, and the series page says Dry-run. Go live with npx vfrey desk series live --id SERIES --confirm CHANNEL_ID. Also check that the publish switch is on: with publish off the platform is skipped with the code publish_off. See Autopilot.

Go live refuses

Going live needs the channel id typed once. means --confirm was empty. That is not the channel id on file for SERIES. means the id you typed is not one of the enabled platforms’ ids. Copy the id from the series page or npx vfrey desk snapshot --json. No platform is on for this series means turn a platform on first.

A job is waiting for review

A series with review on stops each job in awaiting_review before the render. Open the Review screen, or run npx vfrey desk job approve --id JOB_ID or desk job reject --id JOB_ID --reason TEXT. Only a job that waits for review can be approved means the job is not waiting: check npx vfrey desk snapshot --json. A rejected job shows review_rejected, and desk job retry runs it again. See Autopilot.

`desk job retry` refuses

A job that was cancelled while a worker held it is not retried until that worker has stopped, because it may be in the middle of an upload. Wait a moment, or stop the worker, then retry. vfrey never uploads a video twice. See Autopilot.

A source is refused or skipped

source_url_rejected means an rss source is not an http or https address. A source that fails shows its error code on the Sources screen, and the other sources still run. A vfrey-topics source that cannot be read is skipped with the warning topics_unavailable. See Paid features.

A shader transition fails

Shader transitions are not supported in Remotion scenes means the scene is a React scene. Use an HTML scene with --engine vfrey-framey or hyperframes, or build the effect with Remotion’s interpolate(). vfrey.transition: "NAME" is not a transition type lists the types: run npx vfrey scene transitions. the transitions runtime is not loaded means <script src="vfrey/transitions.js"> is missing before vfrey/vfrey.js. See Shader transitions.

Paid features

Topics, Creators, and Mail need an account, and the hosted service is not live yet. See Plans and credits. Each refusal prints a ✗ line and a Fix: line.

Message	Code	What to do
`vfrey accounts are not live yet.`	none	Expected today. Free features work without an account. If you run your own vfrey server, set `VFREY_API_URL` or pass `--api URL`.
`You are not signed in, or this token was revoked.`	`unauthorized`	Run `npx vfrey login`.
`Sending outreach mail needs a paid plan or a credit top-up.`	`plan_required`	Upgrade, or buy a top-up, at the link in the `Fix:` line. Free accounts can draft mail but not send it. Every other paid feature only needs credits.
`Not enough credits. It needs N credits; you have M.`	`credits_required`	Buy credits at the link in the `Fix:` line. `npx vfrey whoami` shows your balance.
`Too many requests.`	`rate_limited`	Wait a minute and try again.
`vfrey is paused for new data right now.`	`capacity_paused`	Try again later. Results vfrey already has still work.
`Could not reach HOST.` or `HOST did not answer in 15 seconds.`	none	Check your connection and try again.

A refused call is not charged. credits_required means the balance is too low. There are no monthly per-feature limits: credits are the limit.

Mail errors

npx vfrey mail ... turns each server refusal into a ✗ line and a Fix: line.

Status	Message	What to do
403	`An agent cannot approve or send mail.` (or `Only a signed-in member of this org can approve or send mail.`)	Approve and send as yourself, in the Mail screen or with `npx vfrey login` and `mail approve` or `mail send`. An MCP connection can only draft and read.
409	`Approve this draft before sending it.`	A person reads it with `mail show --id ID`, and only if they say so runs `mail approve --id ID`. Editing a draft removes its approval.
409	`Confirm your reply-to address first`	Open the link vfrey emailed to your reply-to address, then check with `npx vfrey mail identity`. Run it with the same flags to send the link again.
409	`This address cannot be mailed.`	The owner opted out, or it bounced. Use another recipient with `mail draft --to OTHER_EMAIL`. Do not try to get around it.
409	A sender identity is needed	Run `npx vfrey mail identity --from-name ... --reply-to ... --postal-address ...`.
409	The draft was already sent, or changed	See it with `mail drafts --status sent`, or read it again with `mail show --id ID`.
429	`Your org reached today's limit of N messages.`	Send the rest after the reset time in the message. The limit protects your sending reputation.
429	Too many confirmation emails for your identity	Wait an hour, then save your identity again.
503	Mail is paused or not set up	Try again later. Nothing was sent or charged.
404	No such draft, or no such creator	`mail drafts` lists your drafts. Look a creator up with `creators show`, or draft without `--creator`.
400	A flag or field is wrong	Fix what it names. `npx vfrey mail --help` lists the flags.

A mail draft needs --kind and --need. --platform goes with --creator, and --creator needs --platform.

Cloud and teams

The hosted service is not live yet, so these commands stop with “vfrey accounts are not live yet” today. Once it is, each refusal prints a ✗ line and a Fix: line. See Teams and cloud.

Message	What to do
`NAME is not linked to a cloud project yet.`	Run `npx vfrey cloud link` in the project. `cloud status` also says if a project is linked.
`N files are different in the cloud (changed there since your last sync), so they were not pushed`	Run `npx vfrey cloud pull`. The newest copy wins and the other is kept as `FILE.conflict-TIME`. Look at the `.conflict` file, keep what you need, and delete it. Then push again.
`N files were not recorded`	Run `npx vfrey cloud push` again. Only what changed is sent.
`N files were not written ... not safe to write into a project`	The cloud sent a path outside `scenes/`, `scripts/`, or `videos/`. Nothing outside those is ever written.
`limit_reached` on a push (`meter` is `storage`)	The organization is over its cloud storage. Delete old videos from the cloud project, or upgrade. Push without `--videos` to send only scenes and scripts.
`forbidden` (403)	Your role cannot do this. Reviewers read only. Ask an owner or admin, or see the roles table.
`credits_required` on a render	Cloud rendering costs 10 credits per output minute. Buy a top-up, or render on your machine for free instead.
`credits_required` on a render	A render holds credits for its estimate. Buy credits at the link, or render locally.
`capacity_paused` on a render	vfrey is at capacity. Try again later, or render locally.
A render job ends `failed` or `timeout`	The scene failed in the container. Render it locally with `npx vfrey render --scene DIR` to see the `Fix:` line. A scene failure is charged, and a failure on vfrey’s side is not.
A scene edit answers `conflict`	The scene changed since you read it. Read it again, use the new `currentSha256` as `ifMatch`, and retry.
A scene edit answers `bad_request` with `operation`	That operation, counted from 0, did not apply, and nothing was saved. Check the selector with `npx vfrey scene inspect DIR`.
`org use` refuses	Sign in with `npx vfrey login`. A personal API token is bound to one organization and cannot switch.

The dashboard does not load

Run npx vfrey open. It prints the address and starts the dashboard if it is not running. If it fails, read .vfrey/dashboard.log, or run npx vfrey dashboard in the foreground to see the error. See also The dashboard port is taken.

Secrets read as missing

Set CREDENTIALS_KEY to a 32-byte base64 value. Secrets are read back only as present or missing.

Where are my videos

In a project, videos/ (npx vfrey videos lists them with their paths). On the machine desk, ~/.vfrey/renders/JOB_ID.mp4, or under $VFREY_HOME/renders/.

Is vfrey down

Check the status page for the console, the API, cloud rendering and mail. If it shows no incident, send a note from the support page.

Getting Started

Commands

Concepts

Paid features

Teams and cloud

Reference

Resources

Troubleshooting

Nothing happened after tick

Skill not found

Doctor says the skill is not installed, but I installed it

Not in a vfrey project

`npx vfrey` says 404 or not found outside a project

The dashboard is already running

The dashboard port is taken

`open` says the dashboard did not start

A symlinked folder

The first render is slow

An engine shows unavailable

A command or flag is not clear

Doctor reports a problem

The disk is full

Publish is skipped

A video was rejected or blocked

The background worker is not making videos

A series makes videos but nothing uploads

Go live refuses

A job is waiting for review

`desk job retry` refuses

A source is refused or skipped

A shader transition fails

Paid features

Mail errors

Cloud and teams

The dashboard does not load

Secrets read as missing

Where are my videos

Is vfrey down

​Nothing happened after tick

​Skill not found

​Doctor says the skill is not installed, but I installed it

​Not in a vfrey project

​npx vfrey says 404 or not found outside a project

​The dashboard is already running

​The dashboard port is taken

​open says the dashboard did not start

​A symlinked folder

​The first render is slow

​An engine shows unavailable

​A command or flag is not clear

​Doctor reports a problem

​The disk is full

​Publish is skipped

​A video was rejected or blocked

​The background worker is not making videos

​Login says accounts are not live

​A series makes videos but nothing uploads

​Go live refuses

​A job is waiting for review

​desk job retry refuses

​A source is refused or skipped

​A shader transition fails

​Paid features

​Mail errors

​Cloud and teams

​The dashboard does not load

​Secrets read as missing

​Where are my videos

​Is vfrey down

Nothing happened after tick

Skill not found

Doctor says the skill is not installed, but I installed it

Not in a vfrey project

`npx vfrey` says 404 or not found outside a project

The dashboard is already running

The dashboard port is taken

`open` says the dashboard did not start

A symlinked folder

The first render is slow

An engine shows unavailable

A command or flag is not clear

Doctor reports a problem

The disk is full

Publish is skipped

A video was rejected or blocked

The background worker is not making videos

Login says accounts are not live

A series makes videos but nothing uploads

Go live refuses

A job is waiting for review

`desk job retry` refuses

A source is refused or skipped

A shader transition fails

Paid features

Mail errors

Cloud and teams

The dashboard does not load

Secrets read as missing

Where are my videos

Is vfrey down