HeyPuter/puter · error · HttpError

not_found

not_found

Error message

Driver not found: ${ifaceName}:${resolvedName ?? '(no default)'}

What it means

Thrown by POST /drivers/call (404 not_found) when resolve(interface, requestedDriver) returns null: no driver is registered for that interface, and either no default exists or the named driver isn't registered. The message echoes both the interface and the resolved driver name (or '(no default)').

Source

Thrown at src/backend/controllers/drivers/DriverController.ts:254

        } = (req.body ?? {}) as Record<string, unknown>;

        if (!ifaceName || typeof ifaceName !== 'string') {
            throw new HttpError(400, 'Missing or invalid `interface`', {
                legacyCode: 'bad_request',
            });
        }
        if (!method || typeof method !== 'string') {
            throw new HttpError(400, 'Missing or invalid `method`', {
                legacyCode: 'bad_request',
            });
        }
        const requestedDriver =
            typeof driverName === 'string' ? driverName : undefined;

        const driver = this.resolve(ifaceName, requestedDriver);
        if (!driver) {
            const resolvedName = requestedDriver ?? this.getDefault(ifaceName);
            throw new HttpError(
                404,
                `Driver not found: ${ifaceName}:${resolvedName ?? '(no default)'}`,
                { legacyCode: 'not_found' },
            );
        }

        // Only methods in the pre-resolved callable set are dispatchable.
        // This excludes framework/lifecycle hooks (onServerStart, etc.),
        // inherited base methods, and Object.prototype members, none of
        // which are part of any interface's RPC contract.
        const callable = this.#callableMethods.get(driver);
        if (!callable?.has(method)) {
            throw new HttpError(
                404,
                `Method '${method}' not found on driver '${ifaceName}'`,
                { legacyCode: 'not_found' },
            );
        }

View on GitHub (pinned to 908ec23eda)

Solutions

1. Verify the interface token is spelled exactly as registered (e.g. 'puter-chat-completion'); check the driver's registration call.
2. If naming a driver explicitly, ensure that driver class is registered for that interface (getDefault + resolve walk only registered entries).
3. On self-hosted, confirm the provider extension is enabled and onServerStart completed without errors so registration ran.

Example fix

// before
{ interface: 'puter-chat-completions', method: 'complete' }  // typo
// after
{ interface: 'puter-chat-completion', method: 'complete' }

// can't fully validate client-side; at least check known interface tokens
const KNOWN = new Set(['puter-chat-completion', /* ... */]);
if (!KNOWN.has(ifaceName)) throw new Error('unknown interface');

try {
  await callDriver(...);
} catch (e) {
  if (isHttpError(e, 404) && /Driver not found/.test(e.message)) {
    // driver not registered — surface config error, don't retry
  } else throw e;
}

When it happens

Trigger: POST /drivers/call with an interface that has no registered driver; an explicit driver name that is misspelled or belongs to a different interface; calling before the driver's registerClient/Store/Service hook has run (e.g. during early boot or a disabled extension).

Common situations: Extension that provides the driver is disabled or failed to load; typo in the interface or driver token; calling an AI driver interface on a self-hosted install that hasn't configured any provider; version skew where the interface was renamed.

Related errors

• bad_request
• forbidden
• bad_request
• forbidden
• not_found

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