{"record":{"id":"4c68ee9e61818a73","repo":"weaviate/weaviate","slug":"418-maintenance-mode","errorCode":null,"errorMessage":"418 Maintenance mode","messagePattern":"418 Maintenance mode","errorType":"http","errorClass":null,"httpStatus":418,"severity":"warning","filePath":"adapters/handlers/rest/clusterapi/indices.go","lineNumber":233,"sourceCode":"\t\tregexpShardReinit:                regexp.MustCompile(urlPatternShardReinit),\n\t\tregexpAsyncReplicationTargetNode: regexp.MustCompile(urlPatternAsyncReplicationTargetNode),\n\t\tshards:                           shards,\n\t\tdb:                               db,\n\t\tauth:                             auth,\n\t\tmaintenanceModeEnabled:           maintenanceModeEnabled,\n\t\tlogger:                           logger,\n\t}\n}\n\nfunc (i *indices) Indices() http.Handler {\n\treturn i.auth.handleFunc(i.indicesHandler())\n}\n\nfunc (i *indices) indicesHandler() http.HandlerFunc {\n\treturn func(w http.ResponseWriter, r *http.Request) {\n\t\tpath := r.URL.Path\n\t\tif i.maintenanceModeEnabled() {\n\t\t\thttp.Error(w, \"418 Maintenance mode\", http.StatusTeapot)\n\t\t\treturn\n\t\t}\n\t\t// NOTE if you update any of these handler methods/paths, also update the indices_test.go\n\t\t// TestMaintenanceModeIndices test to include the new methods/paths.\n\t\tswitch {\n\t\tcase i.regexpObjectsSearch.MatchString(path):\n\t\t\tif r.Method != http.MethodPost {\n\t\t\t\thttp.Error(w, \"405 Method not Allowed\", http.StatusMethodNotAllowed)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\ti.postSearchObjects().ServeHTTP(w, r)\n\t\t\treturn\n\t\tcase i.regexpObjectsFind.MatchString(path):\n\t\t\tif r.Method != http.MethodPost {\n\t\t\t\thttp.Error(w, \"405 Method not Allowed\", http.StatusMethodNotAllowed)\n\t\t\t\treturn\n\t\t\t}","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/handlers/rest/clusterapi/indices.go#L215-L251","documentation":"The clusterapi indices router returns HTTP 418 (Teapot) with body '418 Maintenance mode' when the node's maintenance-mode flag is enabled. All indices sub-handlers (search, find, aggregations, overwrite, digest) are short-circuited so replicated traffic stops during maintenance operations. The request itself is fine; the node is intentionally not serving.","triggerScenarios":"Any clusterapi indices request sent to a node that was started with maintenance mode enabled (e.g. during shard/offloading maintenance or node replacement).","commonSituations":"Rolling cluster maintenance; leftover maintenance-mode config flag after an operation finished; pointing client traffic at a node still flagged for maintenance.","solutions":["Retry the request against another node not in maintenance mode","Disable maintenance mode (remove the maintenance-mode flag/config) and restart the node","Wait for the maintenance window to complete before resuming replication traffic"],"exampleFix":"// before\nresp, err := client.Get(maintenanceNodeURL + \"/replication/indices/...\")\n// after\nif nodeInMaintenance(maintenanceNodeURL) { resp, err = client.Get(healthyNodeURL + \"/replication/indices/...\") }","handlingStrategy":"retry","validationCode":"// check node health/maintenance flag before sending replication traffic\nresp, err := http.Get(nodeURL + \"/_health/alive\") // plus maintenance-flag check per deployment config","typeGuard":null,"tryCatchPattern":"resp, err := client.Do(req)\nif err != nil { return err }\nif resp.StatusCode == http.StatusTeapot {\n    // node in maintenance mode: fail over to another node, retry with backoff\n    return failoverAndRetry(req)\n}","preventionTips":["Maintain a node list and skip nodes flagged for maintenance","Treat 418 as retryable-on-another-node, not a request error","Clear maintenance-mode flags promptly after maintenance windows","Add alerting on unexpected 418s from replication traffic"],"tags":["http","maintenance-mode","availability"],"backgroundTag":"http-418-maintenance-mode","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}