HeyPuter/puter · error · HttpError

unauthorized

unauthorized

Error message

Authentication required

What it means

The OCR driver requires an authenticated actor in the request-scoped Context (AsyncLocalStorage). Context.get('actor') returned null, meaning the request did not pass through authentication middleware or the middleware did not populate the actor. The OCR endpoint requires authentication because it accesses user credits and metering.

Source

Thrown at src/backend/drivers/ai-ocr/OCRDriver.ts:182

                    '[OCRDriver] Failed to init Mistral:',
                    (e as Error).message,
                );
            }
        }
    }

    async recognize(args: RecognizeArgs) {
        if (args.test_mode) return sampleResponse();

        const provider = this.#resolveProvider(args);
        if (!provider)
            throw new HttpError(500, 'No OCR provider configured', {
                legacyCode: 'internal_error',
            });

        const actor = Context.get('actor');
        if (!actor)
            throw new HttpError(401, 'Authentication required', {
                legacyCode: 'unauthorized',
            });

        const input = args.source ?? args.file;
        if (!input)
            throw new HttpError(400, '`source` is required', {
                legacyCode: 'bad_request',
            });

        const loaded = await loadFileInput(
            this.stores,
            this.services.fs,
            actor,
            input,
            { acceptWebInput: true },
        );

        if (provider === 'aws-textract') {

View on GitHub (pinned to 908ec23eda)

Solutions

1. Ensure the client passes a valid authentication token (API key or session) with the OCR request.
2. Verify the OCR route/controller has the auth gate set in RouteOptions.
3. In tests, set Context.set('actor', mockActor) before calling recognize().

Example fix

// before — calling OCR without auth (client side)
const result = await puter.ai.ocr({ url: 'doc.pdf' });

// after — ensure authentication is established
await puter.auth.signIn(); // or ensure API token is set
const result = await puter.ai.ocr({ url: 'doc.pdf' });

import { Context } from '../../core/context.js';
// Before calling recognize(), verify authentication
const actor = Context.get('actor');
if (!actor) {
  throw new Error('Authentication required');
}
const result = await driver.recognize(args);

When it happens

Trigger: Calling the OCR recognize() method without authentication; the route's auth gate is misconfigured; calling recognize() outside an HTTP request context (e.g. in a test or background job) without setting up Context.

Common situations: The OCR API route is missing the authentication middleware in its RouteOptions; testing the driver directly without mocking Context; a middleware ordering bug causes the actor to not be set before the driver runs.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• unauthorized
• unauthorized
• unauthorized
• unauthorized
• unauthorized

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