기본 콘텐츠로 건너뛰기

Aider Not Working? Fixes for Edit, Token and API Key Errors

Summary: Most Aider problems fall into five buckets: the aider command isn't found, a broken install with dependency conflicts, missing or misnamed API keys, "Failed to apply edit" errors, and token-limit errors. Each has a short, documented fix, and almost all of them come down to installing Aider in its own environment, sending the model less context, or picking a model that follows Aider's edit format. This guide walks through each error in the order you are likely to hit it, checked against Aider's official documentation.

Aider is a free, open-source AI pair programmer that runs in your terminal and edits files inside a git repository using an LLM you connect with your own API key (or a local model). Because it sits between your shell, Python, git and a model provider, a failure can come from any of those four layers. The quickest way to debug is to figure out which layer is complaining before changing anything.

Step 0: Read the announcement lines first

Every time Aider starts, it prints a few "announcement" lines: the Aider version, the main model and its edit format, the weak model, whether a git repo was found, and the repo-map size. Aider's own troubleshooting page asks for exactly these lines when you report a bug, and they answer most questions on their own. For example, if the line says Git repo: none, then /undo and auto-commits can't protect you, and if the edit format is diff on a weak model, edit errors are more likely.

Inside a session you can also type /help <your question>. Aider has indexed its own documentation and answers with that documentation plus the context of your current chat, which is often faster than searching the web.

1. "aider: The term 'aider' is not recognized" (command not found)

This happens most often on Windows, when the folder that pip installs scripts into is not on your PATH or a security setting blocks it. The documented fail-safe is to run Aider as a Python module instead:

python -m aider

That works immediately, but the longer-term fix is to reinstall with one of the isolated installers (see the table below), which put a working aider command on your path.

2. ImportError or "requires somepackage==X.Y.Z" (dependency conflicts)

Aider pins specific versions of its dependencies and is tested only with those. If you pip-install it into the same Python environment as your own project, the two sets of requirements can clash, and you will see pip warnings like aider-chat ... requires somepackage==X.Y.Z, but you have ... or ImportErrors at startup.

Fix: give Aider its own environment

  • Use aider-install, uv or pipx. All three install Aider into a separate environment with the right dependency set.
  • Avoid system package managers such as Homebrew or AUR for Aider; the docs warn they often install it with the wrong dependencies.
  • If you must use plain pip, use a virtual environment and be careful upgrading packages Aider pins. The docs specifically warn about upgrading litellm on your own, because it changes often and sometimes breaks compatibility.

Install methods compared

Method Command (from the official install page) Python it uses Isolated from your project? Best for
aider-install python -m pip install aider-install then aider-install Your Python 3.8–3.13; installs a separate Python 3.12 if needed Yes Most people; the default recommendation
uv uv tool install --force --python python3.12 --with pip aider-chat@latest Python 3.12, downloaded automatically if missing Yes People who already use uv or want a one-line reinstall
pipx pipx install aider-chat Python 3.9–3.12 per the docs Yes People who already manage CLI tools with pipx
Plain pip python -m pip install -U --upgrade-strategy only-if-needed aider-chat Python 3.9–3.12 per the docs Only inside a virtual environment Advanced users; most likely to cause the errors above

One thing worth knowing: the install page lists Python 3.9–3.12 for pip and pipx, but the metadata of the current release on PyPI (aider-chat 0.86.2) requires Python 3.10 up to, but not including, 3.13. If pip says no matching version is found, check python --version first; on Python 3.13 or newer, let aider-install or uv fetch Python 3.12 for you.

3. Model and API key problems

If you don't name a model, Aider looks at which API keys it can find (environment variables, config files, command-line arguments) and picks a model to match. If it finds no keys at all, it offers to connect you to OpenRouter, which has both free and paid models. Surprises usually come from that automatic choice, so be explicit:

aider --model sonnet --api-key anthropic=YOUR_KEY
aider --model deepseek --api-key deepseek=YOUR_KEY

Where keys can live

  • Command line: --openai-api-key and --anthropic-api-key for those two providers; --api-key provider=KEY for everyone else, which simply sets PROVIDER_API_KEY (so --api-key gemini=xxx sets GEMINI_API_KEY).
  • Environment or a .env file: lines like OPENROUTER_API_KEY=.... Aider loads .env files from your home directory, the git repo root, the current directory and any file passed with --env-file, and later ones win.
  • .aider.conf.yml: an api-key: list with entries like - gemini=foo.

Model warnings and what they mean

  • "Unknown context window size and costs, using sane defaults": Aider doesn't recognise the model name. It assumes an unlimited window and zero cost. You can usually ignore this, but check for a typo, because Aider will often add "Did you mean one of these?" with the correct name.
  • "Missing these environment variables": set every variable listed (for Azure, that is the API base, version and key). On Windows, variables set with setx only appear in a new terminal, so restart it.
  • "Unknown which environment variables are required": Aider can't check for you; look up the provider in Aider's LLM docs or the LiteLLM docs.

4. "Failed to apply edit to filename"

This is the most common complaint, and it is usually not a bug in Aider. The model replied with changes in a format Aider didn't expect, so nothing was written to disk. The documented fixes, roughly in the order I would try them:

  1. Shrink the context. The docs note that above about 25k tokens of context, most models get distracted and stop following the system prompt. Add only the files that need editing, because Aider already sends a map of the rest of the repo. Use /drop to remove files, /clear to wipe the chat history, and /tokens to see what each message costs.
  2. Use a stronger model. Weaker and heavily quantised local models are much more likely to break the edit format; the docs describe most local models as "just barely capable" of working with Aider.
  3. Switch to the whole-file format. Start with --edit-format whole. The model rewrites entire files instead of diffs, which costs more output tokens but is easier for weak models to get right.
  4. Try architect mode. Start with --architect or type /chat-mode architect. One model proposes the change and a separate editor model turns it into file edits, which the docs say is often more reliable for models that struggle with edit formats.

A related habit that prevents bad edits: use /ask to agree on a plan first, then switch to /code and say something short like "go ahead". Ask mode never touches files.

5. "Model has hit a token limit!"

Aider never enforces token limits itself; it only passes on the error from the provider, and its token counts are estimates. The error tells you whether input or output was exceeded, and the fix is different for each.

Input or context window exceeded

You sent too much. Drop files you don't need, clear the history, or split large source files so less code has to be in the chat.

Output limit exceeded

Many models can only return a few thousand tokens at once, so a sweeping change gets cut off. Ask for smaller changes per request, break big files apart, and use a model that can return diffs instead of whole files. Note that this pulls in the opposite direction from fix 3 in the edit section: the whole format helps weak models but uses more output, so it can trigger this error on big files.

Proxies and local servers

The docs also point out that non-compliant API proxies and bugs in local model servers can produce false token-limit errors. If you use a proxy, try connecting directly to the provider once to rule it out.

6. Local models with Ollama behave strangely

If you run Aider against Ollama, use the ollama_chat/<model> prefix (the docs recommend it over ollama/) and set OLLAMA_API_BASE, usually http://127.0.0.1:11434. The bigger trap is Ollama's default context window, which the Aider docs give as 2k tokens. Ollama silently drops anything beyond it, so the model may seem to "forget" your files. Aider now sizes the window for each request automatically, but you can pin a larger fixed one with num_ctx in a .aider.model.settings.yml file, or start the server with OLLAMA_CONTEXT_LENGTH=8192 ollama serve as the docs show. If Ollama itself won't start or can't see your GPU, our Ollama troubleshooting guide covers that side.

7. Undoing a bad change

When Aider runs in a git repo, it commits every edit with a descriptive message and first commits any uncommitted work of yours separately, so your changes and its changes never mix. That means /undo discards the last AI change and /diff shows what changed since your last message. If you launched it with --no-git or --no-auto-commits, you lose that safety net, so keep your own backups. Also note that by default Aider skips pre-commit hooks; add --git-commit-verify if your repo depends on them.

Editor's note

Who Aider suits: developers who are comfortable in a terminal and git, and who want to choose and pay for their own model. Who it doesn't suit: people who want a graphical editor panel or a fixed monthly plan; an IDE extension is a better fit there (see our Cline tutorial).

Gotchas I found while checking the docs: the Python versions on the install page (3.9–3.12) and on PyPI for the current release (3.10–3.12) don't match exactly; the docs' "capable model" list still names older models such as GPT-4o and Claude 3.7 Sonnet, so treat it as a minimum bar rather than a current ranking; and if Aider auto-selects OpenRouter, a free OpenRouter model has its own rate limits (our OpenRouter free models breakdown explains them).

Fast fixes: command not found, run python -m aider; ImportError, reinstall with aider-install or uv; edit errors, /drop files, then try --edit-format whole or --architect; output limit, ask for smaller changes.

FAQ

Is Aider free?

Aider itself is open source and free to install. What you pay for is the model: your provider bills you for API usage, or you run a local model through something like Ollama at no API cost.

Why does Aider keep picking a model I didn't choose?

Without --model, it chooses based on whichever API keys it finds in your environment, .env files and config. Pass --model explicitly, or remove stray keys from a .env file in your home directory.

How do I report a bug so it gets fixed quickly?

Open an issue on Aider's GitHub (or ask in its Discord) and paste the announcement lines from startup, which include the Aider version and the model and edit format you used.

Start with the announcement lines, fix one layer at a time, and most Aider errors take minutes rather than an afternoon.

Image credits: one frame from the official demo video on aider.chat and three screenshots of the public Aider documentation, all at the end of this post.

Last verified: 2026-10-28

Sources:
Aider docs: Troubleshooting
Aider docs: File editing problems
Aider docs: Token limits
Aider docs: Dependency versions
Aider docs: Aider not found
Aider docs: Models and API keys
Aider docs: Model warnings
Aider docs: API keys
Aider docs: Installation
Aider docs: Chat modes
Aider docs: Ollama
Aider docs: Git integration
PyPI: aider-chat

Uploaded Image Uploaded Image Uploaded Image Uploaded Image

댓글

이 블로그의 인기 게시물

브루(Vrew) 요금제 정리: 무료 200크레딧으로 어디까지 쓸 수 있나

요약: 영상 자막 편집기 브루(Vrew)는 2026년 4월 22일부터 기능별 사용량 대신 '통합 크레딧' 하나로 요금을 매겨요. 무료 플랜은 매달 200크레딧이 들어오는데, 음성 분석(자동 자막)만 쓰면 최대 200분 분량이라 짧은 영상 몇 편은 충분하지만, 영상 초반의 Vrew 마크를 지우려면 유료 플랜이 필요해요. 이 글은 브루 공식 가격 페이지와 고객센터 공지를 2026년 10월 23일에 다시 확인해, 크레딧 계산법과 플랜 고르는 기준을 정리했어요. 목차 브루 요금 구조: 통합 크레딧이란 1크레딧으로 할 수 있는 일 무료 플랜으로 되는 것과 안 되는 것 유료 플랜 4종 비교표 월 구독·연 구독·기간 이용권, 무엇이 이득일까 상황별 추천: 학생·직장인·유튜버 크레딧이 모자랄 때: 사용 기록 지우개 업그레이드·환불 전에 알아둘 규칙 운영자 메모, 자주 묻는 질문 1. 브루 요금 구조: 통합 크레딧이란 예전 브루는 플랜마다 음성 분석 몇 분, AI 목소리 몇 자, 번역 몇 자처럼 기능별 한도를 따로 줬어요. 그런데 보이저엑스(브루 운영사)가 실제 이용 데이터를 보니 한두 가지 기능만 집중해서 쓰는 사람이 훨씬 많았다고 해요. 그래서 2026년 4월 22일 업데이트부터는 플랜마다 정해진 크레딧을 받고, 어떤 기능에 쓸지는 내가 정하는 방식으로 바뀌었어요. 플랜별 매달 지급량은 Free 200 · Light 2,000 · Standard 10,000 · Business 12,000크레딧 이에요. 공식 공지에 따르면 무료 사용자는 매달 1일에, 유료 사용자는 매월 결제일에 충전되고, 남은 크레딧은 다음 달로 넘어가지 않아요. 바뀐 뒤 무엇이 좋아졌나 공지에 나온 예시가 이해하기 쉬워요. Standard 플랜에서 AI 목소리만 쓰면 예전에는 최대 50만 자였지만, 지금은 1만 크레딧을 모두 AI 목소리에 몰아 쓸 수 있어 최대 100만 자가 돼요. 반대로 여러 기능을 골고루 쓰는 사람은 크레딧이 기능끼리 ...

에이닷 전화 vs 익시오: 통화 녹음·AI 요약, 내 통신사·폰에 맞는 앱 고르기

요약: 통화 녹음과 AI 요약을 쓰고 싶다면 먼저 내 통신사와 휴대폰 종류부터 확인해야 해요. LG유플러스 고객은 무료 앱 익시오, SKT 고객은 에이닷 전화가 가장 기능이 많고, 다른 통신사의 아이폰 사용자는 iOS에 들어 있는 기본 통화 녹음·전사 기능이 현실적인 선택이에요. 이 글은 2026-10-30에 SKT·LG유플러스·Apple 공식 페이지와 도움말을 직접 확인해 세 가지를 비교했어요. 왜 '앱 기능'보다 '내 조건'을 먼저 봐야 할까요 통화 요약 앱 비교 글을 보면 기능 목록부터 나열하는 경우가 많아요. 그런데 실제로 써 보려는 사람에게 가장 먼저 걸리는 건 기능이 아니라 이용 조건 이에요. 익시오는 LG유플러스 고객 전용이고, 에이닷 전화는 누구나 설치할 수 있지만 통역콜·baro 같은 기능은 SKT 고객에게만 열려 있어요. 아이폰은 운영체제 구조상 앱이 통화를 마음대로 녹음하기 어려워서, 통신사 앱이 안 되면 iOS 기본 기능에 기대야 해요. 그래서 이 글은 "어떤 앱이 제일 좋은가"보다 "내 통신사·내 폰에서 무엇을 쓸 수 있나" 순서로 정리했어요. 기능 차이는 그다음이에요. 한눈에 비교: 에이닷 전화 vs 익시오 vs 아이폰 기본 통화 녹음 구분 에이닷 전화 (SKT) 익시오 ixi-O (LG유플러스) 아이폰 기본 통화 녹음 (Apple) 누가 쓸 수 있나 통신사 구분 없이 앱 설치 가능. 단, 통역콜·baro·그룹통화 발신 등은 SKT 고객 전용 U+ 모바일 고객. 타 통신사, 만 14세 미만, 선불요금제 고객은 제한 (공식 사이트 FAQ상 알뜰폰 중 KB리브엠은 예외) 지원 국가·언어의 iPhone 사용자. 1명과 통화할 때만 녹음 가능 지원 OS·기기 Android 10 이상, iOS 16 이상 iOS 17 이상 iPhone 12 이상 / Android...

타입캐스트 vs 클로바더빙: 수익 나는 채널에 쓸 때 무료·유료 조건 비교

요약 타입캐스트와 클로바더빙은 둘 다 글만 입력하면 한국어 AI 목소리를 만들어 주는 서비스지만, 무료로 쓸 수 있는 범위가 꽤 다릅니다. 클로바더빙 무료는 매달 15,000자까지 쓸 수 있는 대신 수익이 생기는 채널에는 쓸 수 없고, 타입캐스트 무료는 처음에 주는 약 5분 분량의 다운로드로 끝나는 체험판에 가깝습니다. 광고 수익이 붙은 유튜브나 쇼핑몰 영상에 넣을 목소리라면 처음부터 유료 플랜 조건을 보고 고르는 편이 안전합니다. 왜 이 두 서비스를 같이 비교하나 쇼츠 내레이션, 수업 자료 더빙, 상품 소개 영상처럼 "내 목소리 대신 AI 목소리"가 필요할 때 한국 사용자들이 가장 많이 찾는 곳이 네오사피엔스의 타입캐스트 와 네이버의 클로바더빙 입니다. 기능 소개만 보면 비슷해 보이지만, 실제로 문제가 되는 건 음질보다 "이 목소리를 내 채널에 써도 되나" 입니다. 그래서 이 글은 기능 나열보다 무료 사용 범위, 출처 표기 의무, 유료 플랜 가격과 다운로드 한도를 중심으로 정리했습니다. 모든 수치는 2026년 10월 25일에 두 서비스의 공식 요금 페이지와 고객센터 도움말에서 직접 다시 확인한 내용입니다. 한눈에 보는 비교표 항목 타입캐스트 무료 타입캐스트 베이직 클로바더빙 Free 클로바더빙 Standard 월 요금 0원 9,900원 (연간 결제 시 10% 할인) 0원 19,900원 (네이버 클라우드 플랫폼에서 결제) 무료·포함 사용량 음성 생성·재생 무제한, 다운로드는 최초 3,000크레딧(약 5분) 1회 지급 월 30,000크레딧(약 60분) 월 15,000자, 다운로드 월 20회, 프로젝트 누적 5개 (매월 1일 갱신) 월 30,000자, 다운로드 월 40회, 프로젝트 누적 20개 쓸 수 있...