QodeAssist/docs/troubleshooting.md

Troubleshooting

Connection Issues

1. Verify provider URL and port

Make sure you're using the correct default URLs:

• Ollama: http://localhost:11434
• LM Studio: http://localhost:1234
• llama.cpp: http://localhost:8080

2. Check agent and model compatibility

• Ensure each Agent Pipelines slot (QodeAssist > General) has an agent assigned — an unassigned slot disables that feature
• Verify the agent's model exists on your provider (check the agent on the QodeAssist > Agents page)
• Some models may not support certain features (e.g., tool calling or native FIM completion) — pick an agent variant that matches your model

3. Linux compatibility

• Prebuilt binaries support Ubuntu 22.04+
• For other distributions, you may need to build manually
• See issue #48 for known Linux compatibility issues and solutions

Reset Settings

If issues persist, you can reset settings to their default values:

1. Open Qt Creator → Settings → QodeAssist
2. Select the settings page you want to reset
3. Click "Reset Page to Defaults" button

Note:

• API keys are preserved during reset
• Resetting the General page restores the default local Ollama agent pipelines — re-assign your own agents afterwards

Chat History Migration

Images not showing in old chats (version 0.5.x → 0.6.x)

If you have chat histories from QodeAssist version 0.5.x or earlier, images may not display correctly due to a storage structure change.

Solution: Rename the content folder for each affected chat:

# Navigate to your chat history folder
cd ~/path/to/chat_history

# For each chat file, rename its folder
mv chat_name_images chat_name_content

Example:

mv my_conversation_2024-11-28_images my_conversation_2024-11-28_content

What changed:

• Old format (v0.1): Stored files in chat_name_images/
• New format (v0.2): Stores all content in chat_name_content/ (both images and text files)

Common Issues

Plugin doesn't appear after installation

1. Restart Qt Creator completely
2. Check that the plugin is enabled in About Plugins
3. Verify you downloaded the correct version for your Qt Creator

No suggestions appearing

1. Check that code completion is enabled in QodeAssist settings
2. Verify your provider/model is running and accessible
3. Check Qt Creator's Application Output pane for error messages
4. Try manual suggestion hotkey (⌥⌘Q on macOS, Ctrl+Alt+Q on Windows/Linux)

Chat not responding

1. Verify your API key is configured correctly (for cloud providers)
2. Check internet connection (for cloud providers)
3. Ensure the provider service is running (for local providers)
4. Look for error messages in the chat panel

Getting Help

If you continue to experience issues:

1. Check existing GitHub Issues
2. Join our Discord Community for support
3. Open a new issue with:
   • Qt Creator version
   • QodeAssist version
   • Operating system
   • Provider and model being used
   • Steps to reproduce the problem