# WhatBroke

> Plain-English answers when AI goes wrong—and before you trust it.

Every page documents one symptom of an AI coding tool misbehaving, in a fixed shape:
what you saw, what it actually means, the fix, how to stop it happening again.
Content is free to quote with attribution and a link to the page.

## Symptoms
- [My agent calls a tool with invalid or made-up arguments](https://whatbroke.editforge.online/agent-calls-a-tool-with-invalid-arguments/): The model is filling in a schema it does not fully understand, so it invents plausible values. Fix it at the schema, not the prompt: make every parameter strictly typed with enums and required fields, describe each one in the schema itself, and return a specific, correctable error instead of a generic failure.
- [The AI agent is stuck in a loop, making the same change over and over](https://whatbroke.editforge.online/ai-agent-stuck-in-a-loop/): The agent is working from a stale picture of your code. It makes an edit, re-reads something that contradicts it, and "fixes" it back. Stop the run — do not let it keep going — then give it one verifiable goal and a command that tells it when it is done.
- [The AI imported a package that doesn't exist ("module not found")](https://whatbroke.editforge.online/ai-imported-a-package-that-does-not-exist/): The model invented a plausible-sounding library. It is called package hallucination, and it is normal: models predict likely text, and a tidy name like react-use-debounce-hook looks exactly like a real package. Verify the package exists on the registry before you install it — and never install a hallucinated name on faith, because attackers deliberately register the common ones.
- [The AI rewrote my whole file when I asked for one small change](https://whatbroke.editforge.online/ai-rewrote-my-whole-file/): Regenerating the file is easier for the model than surgically patching it, so unless you constrain it, it rewrites — and quietly drops comments, edge cases and anything it judged unnecessary. Ask for a diff, not a file, and keep a clean git tree so you can always see exactly what it removed.
- [My AI video character's face changes between shots](https://whatbroke.editforge.online/ai-video-character-face-changes-between-shots/): Text prompts do not carry identity between generations. Each clip is sampled independently, so the same description produces a different face. Fix it by driving identity from reference images or a locked first frame, not from words.
- [My AI video clip is shorter than I asked for](https://whatbroke.editforge.online/ai-video-clip-is-shorter-than-i-asked-for/): Most hosted video models have a fixed clip length and silently ignore any duration you ask for in the prompt. Veo 3.1 generates 8-second clips. To go longer you extend a previous clip or stitch shots — you cannot prompt your way to a 30-second take.
- [My AI voiceover ignores pauses, or speeds up and adds noises](https://whatbroke.editforge.online/ai-voiceover-pauses-and-pacing-are-wrong/): Newer ElevenLabs models do not support SSML break tags, and overusing break tags in older ones causes instability — the voice speeds up or adds artefacts. Control pacing with punctuation and line structure, and split long scripts into chunks.
- [Claude Code says "context left until auto-compact" — what it means](https://whatbroke.editforge.online/claude-code-context-left-until-auto-compact/): It is a fuel gauge, not an error. When the conversation gets close to the limit you set, Claude Code summarises everything so far and keeps going from the summary. Nothing is lost from your files, but detail from earlier in the conversation is. Run /compact yourself at a clean stopping point instead of letting it fire mid-task.
- [Claude Code: "String to replace not found in file"](https://whatbroke.editforge.online/claude-code-string-to-replace-not-found-in-file/): The Edit tool does an exact character-for-character match, and the text it is searching for no longer matches the file — usually because the file changed since it was read, or because whitespace, indentation or invisible characters differ. Make it re-read the file immediately before editing, and have it edit a short unique anchor rather than a long block.
- [Colour and exposure jump between my AI video clips](https://whatbroke.editforge.online/color-and-exposure-jump-between-ai-clips/): Each generation picks its own lighting, white balance and grade, so clips that should match do not. Fix it by matching on a reference frame in the edit — a one-pass grade per shot — rather than trying to prompt identical lighting.
- [Cursor keeps editing the wrong file](https://whatbroke.editforge.online/cursor-keeps-editing-the-wrong-file/): Cursor edits what it believes you meant, and it guesses from whatever is in its context: the open tab, the last file it touched, or a same-named file elsewhere in the repo. Fix it by naming the exact path with @, and by keeping only the relevant file open when you ask.
- [My AI coding bill is much higher than expected](https://whatbroke.editforge.online/my-ai-coding-bill-is-higher-than-expected/): Almost always input tokens, not output. Every turn of a conversation resends the entire history, so cost grows with the square of the conversation length, and agents that read large files re-send those files on every subsequent step. Start new sessions often, enable prompt caching, and check usage per request before changing model.
- [npm run build fails but the dev server works fine](https://whatbroke.editforge.online/npm-run-build-fails-but-dev-server-works/): The dev server is permissive and lazy; the production build is strict and compiles everything. Code the agent wrote can run fine in dev and still fail type checking, linting, or prerendering at build time. Run the real build locally before you push — that is the only check that matches what your host runs.
- [429 rate_limit_error from the AI API](https://whatbroke.editforge.online/rate-limit-error-429-from-the-ai-api/): HTTP 429 means you exceeded a quota in the current window — requests per minute, input tokens per minute, or output tokens per minute — not that your key is broken. Read the retry-after header, back off exponentially with jitter, and check which of the three limits you actually hit before you change anything else.
- [The AI deleted code that was working](https://whatbroke.editforge.online/the-ai-deleted-code-that-was-working/): Nothing deleted your code on purpose. The model rewrote a file from its own partial view of it, and anything it had not read — or had forgotten — simply did not appear in the new version. Recover with git, then stop whole-file rewrites: demand diffs, not replacements.
- [My video agent pipeline produced a black or zero-byte file](https://whatbroke.editforge.online/video-pipeline-produced-a-black-or-zero-byte-file/): Almost always a failure that was never checked: a generation job that finished with an error status, a download that returned an error page, or an ffmpeg step whose exit code was ignored. Validate every artefact before the next stage consumes it.
- [It works in the preview but breaks when I deploy it](https://whatbroke.editforge.online/works-in-preview-but-breaks-when-deployed/): In nine cases out of ten the deployed environment is missing something the preview had: an environment variable, a build step, a database connection, or a hardcoded localhost URL. Open the deploy logs and the browser console first — the preview told you nothing because it never ran the production build.

## Video agent use cases
What you can and cannot hand to an AI agent in a video pipeline. Each entry gives a verdict (yes / partly / not yet), what works today, where it breaks, and how to wire it up.
- [Can an AI agent assemble an edit, not just generate clips?](https://whatbroke.editforge.online/video-agents/assemble-an-edit-from-a-shot-list/) [partly]: Partly. An agent can build a competent assembly edit — correct order, trimmed to the narration, transitions, music bed — because that is a planning task. It cannot make the judgement calls that separate an assembly from a finished edit: rhythm, when to hold, when to cut early.
- [Can an AI agent cut a long video into short clips?](https://whatbroke.editforge.online/video-agents/cut-long-video-into-short-clips/) [yes]: Yes — this is the most reliable video job you can hand an agent today. Transcribe with word-level timestamps, have a text model pick the segments, then cut with ffmpeg. The agent chooses the moments; ffmpeg performs the cut, so the output stays frame-accurate and deterministic.
- [Can an AI agent make a whole video end to end, unsupervised?](https://whatbroke.editforge.online/video-agents/generate-a-full-video-end-to-end/) [partly]: Partly. An agent can reliably produce a short narrated video — script, voiceover, visuals, assembly, captions, upload — without you touching it. What it cannot do unsupervised is guarantee the result is good. Expect to review every output; the win is that reviewing takes two minutes instead of two hours.
- [Can an AI agent generate and burn in captions?](https://whatbroke.editforge.online/video-agents/generate-and-burn-in-captions/) [yes]: Yes, completely, and it is the highest-return thing to automate first. Transcribe the finished audio, write SRT or ASS, burn in with ffmpeg. The only rule that matters: caption the audio that exists, never the script you wrote.
- [Can an AI agent keep the same character across every shot?](https://whatbroke.editforge.online/video-agents/keep-a-character-consistent-across-shots/) [partly]: Partly, and only if you stop asking the model to remember. Consistency comes from pinning an external reference — a locked character sheet, reference images passed on every call, or a trained likeness — not from describing the character well. Prompt-only consistency fails within about three shots, every time.
- [Can an AI agent colour-match shots from different generations?](https://whatbroke.editforge.online/video-agents/match-color-across-generated-shots/) [partly]: Partly. An agent can measure and correct exposure, white balance and contrast automatically, which fixes most of the mismatch between independently generated clips. What it cannot do is invent a look, or rescue shots whose lighting direction genuinely disagrees — that has to be fixed at generation time.
- [Can an AI agent check its own render before publishing?](https://whatbroke.editforge.online/video-agents/qc-a-render-before-it-publishes/) [yes]: Yes, and this is the single highest-value gate in any video pipeline. Most of a pipeline's checks need no model at all — duration, black frames, silent audio, loudness, resolution are all ffprobe and ffmpeg filters. Add a vision model only for the handful of judgements maths cannot make.
- [Can an AI agent upload and schedule videos to YouTube?](https://whatbroke.editforge.online/video-agents/upload-and-schedule-to-youtube/) [yes]: Yes, through the YouTube Data API — upload, title, description, tags, thumbnail, playlist and scheduled publish time are all programmable. The constraint is not capability, it is quota: a default API project gets a limited daily allowance and an upload is expensive, so an agent that retries carelessly will run out of quota rather than fail loudly.
- [Can an AI agent write and voice a narration track?](https://whatbroke.editforge.online/video-agents/write-and-voice-a-narration-track/) [yes]: Yes. Script-to-voiceover is the most dependable stage in any AI video pipeline — the text is cheap, the audio is fast, and the output is deterministic enough to build an edit around. The failure mode is not quality, it is pacing: synthetic reads do not breathe where a human would.

## About
- [About](https://whatbroke.editforge.online/about/): how pages are structured and how the site is funded.
- [Newsletter](https://whatbroke.editforge.online/newsletter/): What Broke This Week.