copy

website/docs/troubleshooting/edit-errors.md

@@ -0,0 +1,42 @@
+---
+parent: Troubleshooting
+nav_order: 10
+---
+
+# File editing problems
+
+Sometimes the LLM will reply with some code changes
+that don't get applied to your local files.
+In these cases, aider might say something like "Failed to apply edit to *filename*"
+or other error messages.
+
+This usually happens because the LLM is disobeying the system prompts
+and trying to make edits in a format that aider doesn't expect.
+Aider makes every effort to get the LLM
+to conform, and works hard to deal with
+LLMM edits that are "almost" correctly formatted.
+
+But sometimes the LLM just won't cooperate.
+In these cases, here are some things you might try.
+
+## Use a capable model
+
+If possible try using GPT-4o or Opus, as they are the strongest and most
+capable models.
+
+Weaker models
+are more pront to
+disobeying the system prompt instructions.
+Most local models are just barely capable of working with aider,
+so editing errors should be expected.
+
+## Reduce distractions
+
+Many models now have very large context windows,
+but filling them with irrelevant code often
+cofuses the model.
+
+- Don't add too many files to the chat, *just* add the files you think need to be edited.
+Aider also sends the LLM a [map of your entire git repo](https://aider.chat/docs/repomap.html), so other relevant code will be included automatically.
+- Use `/drop` to remove files from the chat session which aren't needed for the task at hand. This will reduce distractions and may help GPT produce properly formatted edits.
+- Use `/clear` to remove the conversation history, again to help GPT focus.

website/docs/troubleshooting/warnings.md

@@ -0,0 +1,70 @@
+---
+parent: Troubleshooting
+nav_order: 900
+---
+
+# Model warnings
+
+Aider supports connecting to almost any LLM,
+but it may not work well with less capable models.
+If you see the model returning code, but aider isn't able to edit your files
+and commit the changes...
+this is usually because the model isn't capable of properly
+returning "code edits".
+Models weaker than GPT 3.5 may have problems working well with aider.
+
+Aider tries to sanity check that it is configured correctly
+to work with the specified model:
+
+- It checks to see that all required environment variables are set for the model. These variables are required to configure things like API keys, API base URLs, etc.
+- It checks a metadata database to look up the context window size and token costs for the model.
+
+Sometimes one or both of these checks will fail, so aider will issue
+some of the following warnings.
+
+## Missing environment variables
+
+```
+Model azure/gpt-4-turbo: Missing these environment variables:
+- AZURE_API_BASE
+- AZURE_API_VERSION
+- AZURE_API_KEY
+```
+
+You need to set the listed environment variables.
+Otherwise you will get error messages when you start chatting with the model.
+
+
+## Unknown which environment variables are required
+
+```
+Model gpt-5: Unknown which environment variables are required.
+```
+
+Aider is unable verify the environment because it doesn't know
+which variables are required for the model.
+If required variables are missing,
+you may get errors when you attempt to chat with the model.
+You can look in the
+[litellm provider documentation](https://docs.litellm.ai/docs/providers)
+to see if the required variables are listed there.
+
+## Unknown model, did you mean?
+
+```
+Model gpt-5: Unknown model, context window size and token costs unavailable.
+Did you mean one of these?
+- gpt-4
+```
+
+If you specify a model that aider has never heard of, you will get an
+"unknown model" warning.
+This means aider doesn't know the context window size and token costs
+for that model.
+Some minor functionality will be limited when using such models, but
+it's not really a significant problem.
+
+Aider will also try to suggest similarly named models,
+in case you made a typo or mistake when specifying the model name.
+
+