{"record":{"id":"7fad00728f6f0b58","repo":"t8y2/dbx","slug":"xugu-operation-timed-out","errorCode":null,"errorMessage":"xugu operation timed out","messagePattern":"xugu operation timed out","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/xugu/protocol_error.go","lineNumber":19,"sourceCode":"package main\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"database/sql/driver\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"net\"\n\t\"regexp\"\n\t\"strconv\"\n\t\"strings\"\n)\n\nvar (\n\terrAgentSessionLimit     = errors.New(\"agent session limit reached\")\n\terrAgentSessionNotFound  = errors.New(\"agent session not found\")\n\terrXuguOperationTimeout  = errors.New(\"xugu operation timed out\")\n\terrXuguOperationCanceled = errors.New(\"xugu operation canceled\")\n\n\t// go-xugu-driver exposes server errors as plain strings rather than a typed\n\t// error. Match only the stable server error header and keep the complete\n\t// original message for diagnostics. A response can contain more than one\n\t// Xugu error; vendorCode intentionally records the first/top-level code.\n\txuguServerErrorHeader = regexp.MustCompile(`(?im)^[\\t ]*(?:error:[\\t ]*)?\\[[\\t ]*E([0-9]{1,9})(?:[\\t ]+L([0-9]+))?(?:[\\t ]+C([0-9]+))?[\\t ]*\\]`)\n\txuguQueryTimeout      = regexp.MustCompile(`(?i)^query timed out after [1-9][0-9]*s$`)\n)\n\ntype rpcError struct {\n\tCode    int           `json:\"code\"`\n\tMessage string        `json:\"message\"`\n\tData    *rpcErrorData `json:\"data,omitempty\"`\n}\n\ntype rpcErrorData struct {\n\tCategory           string `json:\"category\"`","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/xugu/protocol_error.go#L1-L37","documentation":"errXuguOperationTimeout is a sentinel error (errors.New) returned by classifyRPCError and wrapped into the final error when an Xugu driver RPC exceeds its configured timeout. It signals the operation did not complete in time; the wrapped text includes the timeout in seconds and, when available, the underlying driver error. It uses %w so callers can match with errors.Is.","triggerScenarios":"classifyRPCError sets timedOut for a driver RPC (query/execute) and main.go:4320-4322 returns fmt.Errorf(\"%w after %ds...\", errXuguOperationTimeout, timeoutSecs, ...) — i.e. any Xugu operation whose elapsed time exceeded the configured timeout_secs, with or without an accompanying operationErr.","commonSituations":"Long-running queries on large tables, network latency or packet loss to the Xugu server, server under load, a timeout_secs configured too low for the workload, blocked locks on server-side objects.","solutions":["Increase the configured Xugu timeout (timeout_secs) to cover the slowest expected query","Check network latency/stability between client and Xugu server and re-run","Profile and optimize the offending query (indexes, filters, smaller result sets)","Inspect the wrapped operationErr for a server-side cause (locks, load) and address it","Add retry logic with backoff for idempotent read operations"],"exampleFix":"// before\nresult, err := conn.Query(ctx, longQuery) // times out after default 30s\n// after\ncfg.TimeoutSecs = 300 // raise timeout for heavy analytical queries\nresult, err := conn.Query(ctx, longQuery)\nif errors.Is(err, errXuguOperationTimeout) { /* handle */ }","handlingStrategy":"try-catch","validationCode":"// Go: pre-check the configured timeout before issuing slow queries\nif cfg.TimeoutSecs < estimatedMaxQuerySeconds {\n    cfg.TimeoutSecs = estimatedMaxQuerySeconds\n}","typeGuard":"func IsXuguOperationTimeout(err error) bool {\n    return errors.Is(err, errXuguOperationTimeout)\n}","tryCatchPattern":"result, err := conn.Query(ctx, q)\nif errors.Is(err, errXuguOperationTimeout) {\n    // increase timeout / retry or surface a timeout-specific message\n    return fmt.Errorf(\"query exceeded %v: %w\", cfg.TimeoutSecs, err)\n}","preventionTips":["Set timeout_secs above your slowest expected query, not just the typical one","Monitor query durations and alert before the timeout is hit","Use errors.Is against errXuguOperationTimeout rather than string matching","Retry idempotent reads with backoff on timeout"],"tags":["xugu","timeout","database","network"],"backgroundTag":"operation-timed-out","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}