What causes "Model not found: ${args.model}" in HeyPuter/puter?

Use a model from the configured list — enumerate available models via the models endpoint first.

HeyPuter/puter · error · HttpError

bad_request

bad_request

Error message

Model not found: ${args.model}

What it means

Raised by the AI chat `complete()` driver when `_resolveModel(args.model, intendedProvider)` returns null — the requested model name is not registered/available on this backend for the given provider. A `provider` with no matching model, a typo, or a model not configured/disabled all land here.

Source

Thrown at src/backend/drivers/ai-chat/ChatCompletionDriver.ts:325

            throw new HttpError(401, 'Authentication required', {
                legacyCode: 'unauthorized',
            });

        let intendedProvider = args.provider || '';
        if (!args.model && !intendedProvider) {
            intendedProvider = 'azure-openai'; // default provider
        }
        if (
            !args.model &&
            intendedProvider &&
            this.#providers[intendedProvider]
        ) {
            args.model = this.#providers[intendedProvider].getDefaultModel();
        }

        let model = this.#resolveModel(args.model, intendedProvider);
        if (!model) {
            throw new HttpError(400, `Model not found: ${args.model}`, {
                legacyCode: 'bad_request',
            });
        }

        if (args.messages) {
            args.messages = normalize_messages(args.messages);
        }
        if (args.tools) {
            normalize_tools_object(args.tools);
        }

        const completionId = crypto
            .randomUUID()
            .replaceAll('-', '')
            .slice(0, 25);

        const validateEvent: EventMap['ai.prompt.validate'] = {
            username: actor.user?.username || '',

View on GitHub (pinned to 908ec23eda)

Solutions

Use a model from the configured list — enumerate available models via the models endpoint first.
Configure the provider and its models on the backend (config/drivers).
Check the spelling of both model and provider; ensure the provider is registered.
If you omit the model, confirm the provider has a default model set.

Example fix

// before
puter.ai.chat('hi', { model: 'gpt-4-turbo-typo' });
// after — use a valid configured model
puter.ai.chat('hi', { model: 'gpt-4o' });

Defensive patterns

Strategy: validation

Validate before calling

// Validate the model against the available list before calling:
const allowed = await listModels();
if (!allowed.includes(args.model)) { throw new Error(`Model not available: ${args.model}`); }

Try / catch

try { await aiChat({ model }); }
catch (e) {
  if (e.code === 'bad_request' && /Model not found/.test(e.message)) { model = await pickDefaultModel(); return aiChat({ model }); }
  throw e;
}

Prevention

Enumerate configured models first and pick from that list.
Double-check spelling of model and provider names.
On self-host, ensure the provider and its models are configured.

When it happens

Trigger: Calling AI completion with a model name that isn't configured; specifying a provider whose model list doesn't include the name; a typo in the model string; the provider isn't registered at all so no default model resolves.

Common situations: Typo in the model name; self-hosted instance without that provider's models enabled; a model deprecated/removed in an upgrade; provider name mismatch.

Related errors

AI-assisted analysis of HeyPuter/puter@908ec23eda (2026-08-12). Data as JSON: /api/errors/8dfd917c6b4f8031. Report an issue: GitHub.