the inference provider returned an unexpected error. Contact

Error message

the inference provider returned an unexpected error. Contact your Teleport administrator

What it means

ErrUnknown is the fallback sentinel for the Teleport LLM proxy: the handler could not classify the failure, so it reports that the inference provider returned an unexpected error. parseProviderError and marshalError return it when a provider response does not match any known error shape.

Source

Thrown at lib/srv/app/llm/errors/errors.go:51

	ErrBadRequest = errors.New("the inference provider rejected the request as invalid. Check the request body for unsupported or invalid fields")
	// ErrCanceled returned when the request is canceled.
	ErrCanceled = errors.New("the request was canceled")
	// ErrUnauthorized returned when the request is unauthorized.
	ErrUnauthorized = errors.New("the inference provider rejected the request due to authentication or authorization configuration. Contact your Teleport administrator")
	// ErrRejected returned when the provider rejects the request.
	ErrRejected = errors.New("the inference provider rejected the request due to usage limits. Contact your Teleport administrator")
	// ErrUnsupported returned when the requested endpoint is not supported.
	ErrUnsupported = errors.New("teleport doesn't support the requested endpoint, please check the list of supported endpoints in the documentation")
	// ErrBadResponse returned when the provider replied the request with an unsupported message or format.
	ErrBadResponse = errors.New("the inference provider returned an unexpected response. Contact your Teleport administrator")
	// ErrConfig returned when the app or app service are misconfigured, requiring admin intervention.
	ErrConfig = errors.New("unable to serve request due to an app configuration error. Contact your Teleport administrator")
	// ErrInternal returned when there is a Teleport processing error (nothing to do with the inference provider).
	ErrInternal = errors.New("unable to serve the request due to an internal error. Contact your Teleport administrator")
	// ErrLimitExceeded returned when Teleport rejects the request due to limit exceeded.
	ErrLimitExceeded = errors.New("tokens quota exceeded. Contact your Teleport administrator")
	// ErrUnknown returned when the handler could not identify the error.
	ErrUnknown = errors.New("the inference provider returned an unexpected error. Contact your Teleport administrator")
)

// ProviderError is an error in the provider format.
type ProviderError struct {
	err    error
	detail string
}

// NewProviderError creates a new provider error with details.
func NewProviderError(err error, detail string, args ...any) *ProviderError {
	if len(args) > 0 {
		detail = fmt.Sprintf(detail, args...)
	}
	return &ProviderError{err, detail}
}

func (e *ProviderError) Error() string {
	return e.UserMessage()

View on GitHub (pinned to 1283425b60)

Solutions

Check the app service logs for the raw provider response captured alongside the wrapped error
Verify the provider API version is one supported by your Teleport release
Ensure no corporate proxy intercepts provider traffic with non-JSON error responses
Retry once; if reproducible, capture the provider payload and report to Teleport maintainers

Defensive patterns

Strategy: type-guard

Type guard

func isUnknownProviderError(err error) bool {
  return errors.Is(err, llmerrors.ErrUnknown)
}

Try / catch

err := doLLMRequest(ctx, req)
if errors.Is(err, llmerrors.ErrUnknown) {
  log.Printf("unclassified provider error, raw payload: %v", unwrapCause(err))
  return fallbackResponse()
}

Prevention

Pin/verify the provider API version supported by your Teleport release
Log full provider responses alongside wrapped errors
Bypass or configure corporate proxies so provider errors stay JSON

When it happens

Trigger: parseProviderError receives a provider error payload it cannot map; ValidateChallengeScope/marshalError paths (per the index) treat unmatched/invalid inputs as unknown; any non-nil provider failure with no recognized category.

Common situations: Provider API versions change and emit new error codes, malformed provider responses, or proxies/gateways in front of the provider return HTML/HTML error pages instead of JSON.

Related errors

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/648dbb06353f6164. Report an issue: GitHub.