Tencent/WeKnora · error

parser engine %q is unavailable: %s

Error message

parser engine %q is unavailable: %s

What it means

errEngineUnavailable reports that a document parser engine is registered in the registry but cannot run in the current context — e.g. it is disabled for this tenant, lacks required credentials, or was compiled out of this build. NewReader surfaces this when the requested engine can't actually be used, with the concrete reason in the message.

Source

Thrown at internal/infrastructure/docparser/engine_registry.go:150

			Available:         available,
			UnavailableReason: reason,
		})
	}

	for _, re := range remoteEngines {
		if seen[re.Name] {
			continue
		}
		result = append(result, re)
	}

	return result
}

// errEngineUnavailable reports an engine that is registered but cannot run for
// this tenant or this build.
func errEngineUnavailable(engine, reason string) error {
	return fmt.Errorf("parser engine %q is unavailable: %s", engine, reason)
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the reason suffix in the error and fix that specific cause (missing credential, disabled flag, etc.).
2. Set the required env/config for the engine (API keys, endpoint) or enable it for the tenant.
3. Fall back to another registered engine available for the tenant via the registry's selection logic.
4. If the engine requires build tags/native deps, rebuild/deploy an image that includes it, or remove it from the requested config.

Example fix

// before
engine: "anydoc" // tenant lacks anydoc credentials
// after
# set credentials or pick an available engine
ANYDOC_API_KEY=... ; engine: "builtin" // fallback until enabled

if !registry.IsAvailable(requestedEngine, tenantID) {
    requestedEngine = registry.DefaultEngine(tenantID)
}

func engineAvailable(reg *EngineRegistry, name, tenant string) bool {
    return reg != nil && reg.IsAvailable(name, tenant)
}

reader, err := NewReader(ctx, cfg)
if err != nil && strings.Contains(err.Error(), "is unavailable") {
    reader, err = NewReader(ctx, cfg.WithEngine(DefaultEngine)) // fallback
}

When it happens

Trigger: Calling NewReader (which resolves an engine by name) for an engine whose availability check fails: tenant not allow-listed, API key missing, engine disabled by config, or binary built without that engine's dependencies.

Common situations: Config requesting an engine (e.g. anydoc/external OCR) whose cloud credentials aren't set in the environment; engine gated behind a license or feature flag off for the tenant; docker image built without CGO/native deps for that engine; typo'd engine name matching a registered-but-disabled engine.

Related errors

• create request: %w
• custom agent configuration is required for agent QA
• summary model (model_id) is not configured in custom agent s
• rerank model is not configured: please set rerank_model_id o
• JWKS document contains no keys

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/b65bc749be942a5a. Report an issue: GitHub.