Troubleshooting Custom Model Configuration Errors in AI Coding IDEs: A Practical Guide

    This guide explains why a custom LLM can save without errors in an AI coding IDE but still return "model not found" on the first request. It covers the five configuration fields behind these failures, including provider type, model ID, API format, base URL, and API key. It also gives a step-by-step checklist and a curl test for isolating the problem.

    1. The Problem: Why Errors Appear After Saving the Configuration

    As AI-assisted programming becomes more common, many developers want to connect their AI coding IDE to the large language model (LLM) services they already use, rather than relying only on the built-in models. A common approach is to add a custom entry in the IDE’s model settings. You choose a provider type, enter a model ID, select an API format, provide a request URL and an API key, then save and start chatting.

    In practice, a frequent pattern appears. The configuration saves without any problem, but the first request returns an error such as “model not found.” This suggests the issue is less about whether the configuration can be saved, and more about a mismatch between one parameter in the request chain and what the remote service expects.

    The sections below break down each configuration field and the likely causes of these errors.

    2. The Five Core Elements of a Custom Model Configuration

    A custom model configuration tells the IDE three things: where to send requests (the address), which protocol to use (the API format), and who is making the request (the model ID and API key). A mistake in any of these causes the request to fail.

    2.1 Choosing the Provider Type

    When you add a model, most AI coding IDEs show a provider dropdown. It usually includes several preset providers and a “Custom” option.

    Keep these points in mind:

    • A preset option usually means the IDE automatically applies that provider’s standard request URL and protocol format.
    • If you connect to a third-party inference service that offers model access through a compatible protocol, its URL and protocol format may differ from any preset.
    • In that case, select “Custom” and specify the request URL and API format manually. Otherwise, the IDE sends requests to the wrong endpoint, which usually returns “model not found” or a similar error.

    Best practice: When you use a non-preset inference endpoint, always choose “Custom.” Do not assume that a preset with a similar name will work.

    2.2 Model ID: The Most Common Pitfall

    “Model not found” errors often relate to the model ID. The model ID is the value of the model field in the request body. The remote service uses it to match against its list of supported models. Common mistakes include:

    • Case mismatch: Some inference services treat model IDs as case-sensitive.
    • Using the display name instead of the API call name: The name shown in the UI may differ from the ID the API requires. Use the call ID listed in the provider’s API documentation.
    • Typos or extra spaces: Spaces or line breaks introduced while copying and pasting will cause the match to fail.
    • Using the wrong capability identifier: Some inference channels built for specific scenarios require their own dedicated model ID, not the ID of a general chat model.

    Troubleshooting: First, send a minimal request directly to the endpoint with curl to check whether the model ID is accepted. For example, to test an OpenAI-compatible endpoint:

    1. curl -X POST https://<your-inference-endpoint>/v1/chat/completions \
    2. -H "Content-Type: application/json" \
    3. -H "Authorization: Bearer <your-api-key>" \
    4. -d '{
    5. "model": "<your-model-id>",
    6. "messages": [{"role": "user", "content": "ping"}]
    7. }'

    If the command returns a normal response, the model ID and API key are valid, and the problem lies elsewhere in the IDE configuration. If it returns “model not found,” check the model ID against the provider’s documentation.

    2.3 API Protocol Format: Another Frequent Source of Errors

    Two main protocols are widely used for chat models today:

    • OpenAI-compatible Chat Completions format: Most inference services and aggregation platforms offer this compatible format.
    • Anthropic-style Messages format: The request and response structures differ noticeably from the first format. For example, system prompts are passed differently, and messages are structured differently.

    If your endpoint accepts only one of these formats but the IDE is set to the other, the server may reject the request or fail to parse its fields. The error messages can vary widely and may include “model not found.”

    How to verify: Check the official API documentation of your provider to confirm which protocol its endpoint paths and request body structure follow. Then set the API format in the IDE to the matching option. The two must match exactly and must not be mixed.

    2.4 Request URL: Check the Path and Version Segments

    A custom request URL usually needs to be the complete base URL that the IDE can use directly. Common mistakes include:

    • Omitting the version path segment, such as /v1.
    • Including the endpoint path. Some IDEs need only the base URL and append /chat/completions automatically. If you enter the full endpoint path, the final URL will be wrong.
    • Mixing endpoint addresses from different protocols. The Messages and Chat Completions formats use different endpoint paths, so the URL must match the API format you selected in Section 2.3.

    Recommendation: After you enter the URL, use the curl command from Section 2.2 to confirm that the URL is reachable and returns a normal response. Then enter the same URL in the IDE.

    2.5 API Keys and Permissions

    Key problems usually appear as authentication errors, such as 401 or 403. Some services, however, issue keys per product line or entitlement. A key may have access to general chat but not to a dedicated channel for coding scenarios. In that case, requests to the dedicated channel can still fail even when the model ID, URL, and format are all correct.

    Check the following:

    • The key was created in the provider’s console and copied in full. Some platforms show the complete key only once, at creation. If you close the dialog without saving it, you must delete the key and create a new one.
    • Your account has been granted access to the model channel or entitlement you are calling.
    • The key has not reached its rate or quota limit. Some services return an unusual message instead of a standard rate-limit code when a quota runs out.

    3. A Systematic Troubleshooting Process

    To find the problem fastest, check the following steps in order:

    1. Verify the model ID. Compare the case, spelling, and spaces character by character against the provider’s API documentation.
    2. Confirm the protocol format. Determine whether the endpoint uses the Chat Completions-compatible format or the Messages format, then select the matching API format in the IDE.
    3. Validate the request URL. Send a request to the URL with curl. Confirm that the URL is complete, the path is correct, and no path segments are missing or extra.
    4. Verify the key and permissions. Confirm that the key is valid, has access to the required channel, and has not run out of quota.
    5. Review the IDE configuration. Confirm that the provider type is “Custom” rather than a similarly named preset. Then save the configuration and start a new session.

    Most “model not found” errors can be traced to one of these steps. The two most common causes are selecting the wrong provider type, which sends requests to the wrong endpoint through a preset, and entering a display name or an incorrect identifier as the model ID.

    4. Configuration Example (Schematic)

    The following shows the fields involved in a typical custom model configuration. Use it as a checklist. Exact field names depend on your IDE.

    1. Provider type: Custom
    2. Model ID: <use the call ID from the provider's documentation>
    3. API format: <OpenAI-compatible or Anthropic Messages, matching the endpoint protocol>
    4. Base URL: <complete base URL, including the version path segment>
    5. API key: <the key created and stored securely in the provider's console>

    This structure is a general illustration and does not represent the parameter specification of any particular vendor. When filling in these fields, always follow the official documentation of your provider.

    5. Summary

    Connecting a custom LLM to an AI coding IDE is essentially a protocol alignment task. The provider type determines where requests go. The API format determines the structure of the request body. The model ID and API key determine whether the remote service accepts the request. An error does not necessarily indicate a serious problem. By checking the model ID, protocol format, request URL, key and permissions, and then the IDE configuration in that order, most issues can be resolved within minutes. Sending a minimal curl request before filling in the IDE configuration saves time.