HeyPuter/puter · error · HttpError

internal_error

internal_error

Error message

No OCR provider configured

What it means

The OCR driver's #resolveProvider method returned null, meaning no OCR provider could be determined for the request. This happens when: (1) the caller didn't pass an explicit provider, (2) no driver alias was set in the Context, and (3) #defaultProvider() returns null because neither AWS Textract credentials nor a Mistral API key were configured in onServerStart(). This is a server-side configuration failure.

Source

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

                this.#mistral = new Mistral({
                    apiKey: mistral.apiKey,
                }) as unknown as MistralOcrClient;
            } catch (e) {
                console.warn(
                    '[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,

View on GitHub (pinned to 908ec23eda)

Solutions

1. Configure at least one OCR provider in config.json under drivers.ai-ocr.providers (either aws-textract with access_key/secret_key, or mistral-ocr with apiKey).
2. Restart the Puter backend so onServerStart() runs and initializes the provider clients.
3. Alternatively, pass an explicit provider parameter in the OCR request if a provider is configured but #defaultProvider() can't auto-detect it.

Example fix

// before — config.json with no OCR providers
"ai-ocr": { "providers": {} }

// after — add at least one provider
"ai-ocr": {
  "providers": {
    "aws-textract": {
      "aws": {
        "access_key": "AKIA...",
        "secret_key": "...",
        "region": "us-west-2"
      }
    }
  }
}

// Server-side: validate at startup that at least one provider is configured
function validateOcrConfig(config) {
  const providers = config.drivers?.['ai-ocr']?.providers ?? {};
  const hasAws = providers['aws-textract']?.aws?.access_key && providers['aws-textract']?.aws?.secret_key;
  const hasMistral = providers['mistral-ocr']?.apiKey;
  if (!hasAws && !hasMistral) {
    throw new Error('At least one OCR provider must be configured');
  }
}

try {
  const result = await driver.recognize(args);
} catch (e) {
  if (e.code === 'internal_error' && e.message === 'No OCR provider configured') {
    // Server misconfiguration — notify admin, degrade gracefully
    showAdminAlert('OCR provider not configured');
  }
}

When it happens

Trigger: The Puter backend is running without any OCR provider configured in config.json (no aws-textract credentials, no mistral-ocr API key). The first OCR request will hit this error because #defaultProvider() has nothing to fall back to.

Common situations: Fresh deployment where OCR providers haven't been configured; config.json was updated but the server wasn't restarted (onServerStart didn't pick up new config); the OCR provider section was accidentally removed from config.

Related errors

• Failed to resolve prepared batch item for index ${index}
• internal_error
• internal_error
• internal_error
• unknown_error

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