Tencent/WeKnora · error

gRPC ListEngines failed: %w

Error message

gRPC ListEngines failed: %w

What it means

ListEngines wraps any error from the unary ListEngines RPC with 'gRPC ListEngines failed: %w'. This RPC asks the docreader which parser engines it offers (names, file types, availability). The wrapped error is the raw gRPC failure: transport problem, server error, deadline, or auth rejection. If the client was never connected, errNotConnected is returned instead.

Source

Thrown at internal/infrastructure/docparser/grpc_parser.go:241

				StorageKey:  img.GetStorageKey(),
				ImageData:   img.GetImageData(),
			})
		}
	}
	return result, nil
}

func (p *GRPCDocumentReader) ListEngines(ctx context.Context, overrides map[string]string) ([]types.ParserEngineInfo, error) {
	p.mu.RLock()
	client := p.client
	p.mu.RUnlock()
	if client == nil {
		return nil, errNotConnected
	}

	resp, err := client.ListEngines(ctx, &proto.ListEnginesRequest{ConfigOverrides: overrides})
	if err != nil {
		return nil, fmt.Errorf("gRPC ListEngines failed: %w", err)
	}

	result := make([]types.ParserEngineInfo, 0, len(resp.GetEngines()))
	for _, e := range resp.GetEngines() {
		result = append(result, types.ParserEngineInfo{
			Name:              e.GetName(),
			Description:       e.GetDescription(),
			FileTypes:         e.GetFileTypes(),
			Available:         e.GetAvailable(),
			UnavailableReason: e.GetUnavailableReason(),
		})
	}
	return result, nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Unwrap the error and inspect the gRPC status code (status.Convert) to distinguish Unavailable (connectivity) from PermissionDenied (auth)
2. Verify the docreader service is running and the configured address resolves and is reachable (grpcurl -plaintext addr list)
3. Increase the context deadline for engine listing on slow/cold-start deployments
4. Check auth/TLS env variables consumed by docclient.LoadAuthConfigFromEnv match the server configuration
5. Retry with backoff for transient Unavailable codes

if !reader.IsConnected() {
    return fmt.Errorf("docreader gRPC client not connected; check DOCREADER address config")
}

var engines []types.ParserEngineInfo
var lastErr error
for attempt := 0; attempt < 3; attempt++ {
    engines, lastErr = reader.ListEngines(ctx, overrides)
    if lastErr == nil {
        break
    }
    if st, ok := status.FromError(errors.Unwrap(lastErr)); ok && st.Code() == codes.Unavailable {
        time.Sleep(time.Duration(1<<attempt) * time.Second) // backoff
        continue
    }
    break // non-transient: don't retry
}
if lastErr != nil {
    return fmt.Errorf("list engines: %w", lastErr)
}

When it happens

Trigger: Calling GRPCDocumentReader.ListEngines while the docreader gRPC server is unreachable, returns a gRPC error (Unavailable, Internal, DeadlineExceeded, PermissionDenied), the context is cancelled/times out, or auth/TLS credentials are rejected on the channel.

Common situations: docreader service not deployed or scaled to zero; wrong DOCTEAM/docreader address in configuration so DNS resolution or connection fails; environment timeout too short when engine discovery is slow (e.g. engines lazily initializing); token auth misconfigured after rotating secrets.

Related errors

• gRPC ReadStream returned no metadata frame
• gRPC Read failed: %w
• create qdrant client: %w
• create milvus client: %w
• anydoc scanned-PDF fallback returned no result for %q

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