FAQ & Troubleshooting

Most problems in Apis AI have one of a handful of causes: a missing key, an empty model list, a folder that was never released, or a chat that has simply become very long. The questions below are sorted by where the trouble shows up.

Start & Display

The window stays black or looks frozen after start

On Linux with Wayland and an NVIDIA graphics card, Compose Desktop occasionally fails to draw the first frame: the window opens but stays black, or it shows a stale, seemingly frozen image – even though the app itself runs normally (you can still close it, and the logs show a clean start). Apis AI therefore switches to software rendering automatically on Wayland. If the problem still appears, start the app once with SKIKO_RENDER_API=SOFTWARE apis-ai. To force the GPU path instead, use SKIKO_RENDER_API=OPENGL apis-ai – an explicitly set environment variable always wins over the built-in default. Under Settings → System → Rendering you can switch on Hardware rendering (experimental): the app then tries the GPU and automatically falls back to software rendering if the GPU delivers no image, telling you about it in the chat. A window that only redraws slowly is not the same as a frozen app: Apis AI notices the difference and keeps a diagnostic file only when the interface was truly blocked – see Where does Apis AI store its files?.

A local model keeps the graphics card busy

A local model provider (llama.cpp on localhost:8080) loads the model into GPU memory and can occupy several gigabytes. Apis AI starts such a server on demand and stops the one it started when you close the app, so it does not linger in the background. A server started by Apis AI is also stopped automatically after an idle timeout (default 5 minutes without a request, configurable; 0 = off) – or immediately with the Stop local server button in the provider's advanced settings. If another program still reports graphics errors, check whether a local Llama server is running (for example with nvidia-smi) and stop it, or switch the provider away from the local endpoint.

Providers & Models

My provider card shows that an API key is missing

Open Settings → Providers & Models and paste the key into the API Key field of that provider. Cloud services issue such a key in their own account area; a local Ollama needs none. After that click Save Settings and reload the model list once.

The model list stays empty

In that order: check the API key, check the Base URL, then load the list again. If you run Ollama on your own computer, it has to be running in the background – if it is not, Apis AI finds no models. Providers that cannot answer without a key show no models at all until the key is entered.

Which model should I pick?

For a new chat Apis AI uses your standard model. Anything you mark with a star lands in your favorites at the top of the list and in the model picker. If a model is labelled No Tool Call Support, it can chat but cannot use extensions, skills or files – for work on your computer choose a model without that note. Which model is currently active is always visible in the sidebar and in the model field of the chat.

A request fails with a limit or quota message

This comes from the service, not from Apis AI: your key has reached its usage limit or is temporarily being throttled. Apis AI automatically retries short failures – you see a countdown in the chat while it does. Otherwise simply wait a moment, or switch to another model or another provider for this chat. An overview of all these messages is in Chat Features.

Chats & Answers

The AI forgets what we talked about earlier

Then the chat has outgrown the context window of the model. Apis AI condenses long chats automatically once they reach the Compression Threshold; while doing so you see Compressing chat… at the end of the conversation (it appears after a moment, so a quick compression does not flash). This works for every provider. Older messages stay visible to you but are no longer sent to the AI. If that happens too early, raise the threshold or pick a provider with a larger Context Window.

An answer stops in the middle

Two common reasons: the maximum answer length (Max. Tokens) is reached, or the model has used up its permitted tool rounds (Max. Tool Rounds). Ask the AI to continue, or raise the limit for this chat. 0 means no limit at all for tool rounds.

Rarely, the cause lies on the service side: some providers send empty fields in the middle of a running answer. Apis AI simply ignores them and keeps writing, so an answer like that no longer breaks off half-way. If an answer really does stop without you having changed anything, just send your message again – the conversation itself is not affected.

Nothing happens after I send

Nothing is broken: a model that is allowed to think takes a moment before the first word appears. In addition, Apis AI tries a failed request again on its own, which is shown in the chat. If it stays quiet for a long time, check whether the provider is reachable – a quick switch to another provider usually shows whether the problem is on the service side. What the individual notices in the chat mean is explained in Chat Features.

The AI suddenly asks me questions

That is intentional, not a hang-up: instead of guessing, the AI asks when a decision affects your work – for example which of two variants it should use. You answer with Continue; if several questions are pending, they appear one after the other (Question 1 of 2). You can take a suggestion, pick several options at once or type your own answer. While it waits for you, the answer is simply paused – nothing is lost, and you can still cancel it with Stop. More in Chat Features.

New chats have odd titles

New chats get either an AI-generated title or the start of your first message, depending on Chat Title Mode in the appearance settings. You can rename a chat at any time.

Files & Folders

The AI does not find my files

Apis AI can only look into folders you have released. Add the folder under Settings → System & Prompts → Shared Folders. Subfolders are included automatically. Without a released folder the AI cannot read or write anything at all. If folders are released and the AI still behaves as if it had no file access, check the card Tool Selection per Model in the Extensions tab: with a model profile, Files & folders may be switched off for exactly this model (see Settings).

It keeps asking before deleting

That is the safe default. As long as Can delete files on its own is off, the AI asks for your confirmation every time. If you work with copies or backups anyway, you can let it delete on its own in the settings.

A command was blocked

The terminal sandbox is active: only allowed, read-only commands are run. Which commands those are is shown in the settings, and you can extend the list. A small safety baseline always stays in place – destructive commands and interpreters are never executed, even if they appear in your list. For a single chat or a workflow step you can decide differently without weakening the general setting. All of this is described in Tools & Security.

Where did my files go after the AI changed them?

The AI normally changes existing files in place and shows you what it is doing. If you work on important data, keep a copy outside the released folders – that way you always have the state from before.

Extensions

My MCP asks for a login

Some services need it. The card of that MCP offers Log In; a security window opens, you sign in with the service and confirm. Afterwards the card shows that the login worked. Step by step in Understanding & Using MCPs.

An MCP does not respond

First check the switch on its card: a switched-off MCP is not available to the AI. After the login, a minute of patience can help, and if in doubt save your settings and start the app once more. Reminder-only entries cannot answer on their own – they prepare the steps for you instead.

My skill does not appear in the chat

Skills that are set to apply automatically are working in the background without showing up as an entry. Only skills that you switch on for each chat by hand appear in the + menu. If a hand-activated skill does not show up there, check whether its switch is on and whether the list is empty – the app tells you when there are no skills available.

When does a rule apply, when a skill?

Rules are permanent instructions for all chats. Skills are capabilities that only step in when they are needed, for example for certain file types. The difference is explained in Rules & Skills.

How do I give the AI rules for a whole project?

Put them into a file named AGENTS.md in the project folder. Apis AI looks for it by itself as soon as the AI works in that folder and follows what is written there – you don't have to attach the file or remind the AI of it. Rules that should apply to you in every project are better kept as rules in the settings. See Rules & Skills.

Background & Workflows

My scheduled workflow did not run

A schedule can only run while Apis AI is running. Switch on Run in the background (system tray) and, if schedules should also survive a reboot, Start automatically when logging into the system. Both are in the settings under Background Service – see Background Service & Schedules.

I do not get any notification about automatic runs

Under Notifications for Scheduled Workflows you can choose Success and Mistakes if you want to be informed about every run, or stay with Only if there are errors to hear only when something went wrong.

A workflow step passes on less text than expected

Very large handover packages are shortened, because the next step would otherwise not fit into the context window. How much may be passed on is set by Max. Handover Characters in the settings; a value given in a step or in the workflow itself takes precedence.

Speech Input

There is no microphone button in the chat

Speech input is disabled by default. Enable it under Settings → System → Speech Input; the microphone and voice chat buttons then appear in the chat input. Details: Speech Input.

The connection test fails

For the local backend, start the server with Start local server – or switch on Start Whisper server automatically, which makes Apis AI start the server itself at every app start – and check ~/.local/state/apis-ai/whisper.log. For the remote backend, check that the URL ends with /v1, the API key is valid and the model name is correct.

Does Apis AI have to start the local Whisper server every time?

No. Enable Start Whisper server automatically in the local speech settings and Apis AI launches whisper-server by itself at every app start and again before transcribing if it is no longer reachable. A server you started yourself is detected and reused, and Apis AI only stops the server it started itself. Details: Speech Input.

Voice chat mode sends too early or too late

Adjust Silence until sending and Speech threshold (VAD) in the speech settings. Raise the threshold in noisy rooms; lower the silence value for quick sentences.

Your Data & Contact

Where does my information go?

Only to the providers you have set up yourself, and only the content that belongs to the request. A local Ollama keeps everything on your computer. Time and system information is attached only if you switch on Send time & system info. Full details are in the legal information inside the app.

Where does Apis AI store its files?

Your settings, chats and logs live in your user folder under .config/apis-ai; the logs are in the logs subfolder and are the first thing to look at when something behaves strangely. Your released folders are not copied anywhere.

If the interface should ever really get stuck, Apis AI writes a single diagnostic file (edt-hang-….dump) into that same folder, so that support can see what the app was doing at that moment. Such a file appears only after a genuine freeze – a window that merely redraws slowly leaves no trace – and at most twenty of them are kept. They are safe to delete at any time.

I want to see what the AI is doing in a chat

Every tool call, every deleted file, every blocked command and every compression is shown in the chat, and every file change as a Git-style diff. If you want to see the exact text the model receives, open Show full prompt in the system settings.

I still need help

In the app under Settings → Legal & Help there is Contact Support, which opens a pre-written e-mail to support@apisclient.com. The legal information and licences are also found there, and work without an internet connection.