{"record":{"id":"97f8745061ebb1ac","repo":"weaviate/weaviate","slug":"cannot-init-handler-w","errorCode":null,"errorMessage":"cannot init handler: %w","messagePattern":"cannot init handler: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"usecases/schema/manager.go","lineNumber":232,"sourceCode":"\tcloud modulecapabilities.OffloadCloud,\n\tparser Parser,\n\tcollectionRetrievalStrategyFF *configRuntime.FeatureFlag[string],\n\tnamespacesExister namespaces.Exister,\n\tdropVectorEnqueuer DropVectorIndexEnqueuer,\n) (*Manager, error) {\n\thandler, err := NewHandler(\n\t\tschemaReader,\n\t\tschemaManager,\n\t\tvalidator,\n\t\tlogger, authorizer,\n\t\tschemaConfig,\n\t\tconfig, configParser, vectorizerValidator, invertedConfigValidator,\n\t\tmoduleConfig, clusterState, cloud, parser, NewClassGetter(&parser, schemaManager, schemaReader, collectionRetrievalStrategyFF, logger),\n\t\tnamespacesExister,\n\t\tdropVectorEnqueuer,\n\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot init handler: %w\", err)\n\t}\n\tm := &Manager{\n\t\tvalidator:    validator,\n\t\trepo:         repo,\n\t\tlogger:       logger,\n\t\tclusterState: clusterState,\n\t\tHandler:      handler,\n\t\tSchemaReader: schemaReader,\n\t\tAuthorizer:   authorizer,\n\t}\n\n\treturn m, nil\n}\n\nfunc (m *Manager) ClusterHealthScore() int {\n\treturn m.clusterState.ClusterHealthScore()\n}\n","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/usecases/schema/manager.go#L214-L250","documentation":"Wraps the failure of NewHandler during Manager construction at startup (MakeAppState). The schema handler — which wires migrator, repo, validators and cluster state — failed to initialize, aborting Weaviate startup. The root cause is always the wrapped error.","triggerScenarios":"Server startup with an invalid configuration for the schema handler: bad storage path, failing migrations on existing schema data, invalid module/vectorizer config validators, or cluster state initialization failure.","commonSituations":"Upgrading Weaviate onto incompatible existing persistence data; PERSISTENCE_DATA_PATH unwritable; corrupted schema files; misconfigured modules referenced in the schema (missing vectorizer config).","solutions":["Read the wrapped cause after 'cannot init handler:' — it names the exact subsystem that failed","Check PERSISTENCE_DATA_PATH exists, is writable, and its schema data is compatible with this Weaviate version","Review recent release notes for breaking schema/config migrations when upgrading versions","Validate module configs (vectorizers, moduleConfig) in the environment and class definitions"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-start checks: writable data dir and version-compatible schema files\nif err := fsx.EnsureWritable(persistenceDataPath); err != nil { log.Fatal(err) }","typeGuard":null,"tryCatchPattern":"appState, err := MakeAppState(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"cannot init handler\") {\n        log.Fatalf(\"schema handler init failed: %v\", err) // surface wrapped cause\n    }\n    log.Fatal(err)\n}","preventionTips":["Read migration/breaking-change notes before upgrading Weaviate versions","Verify PERSISTENCE_DATA_PATH writability and ownership in deployment templates","Back up the data directory before upgrades so corrupt schema state is recoverable"],"tags":["startup","schema","initialization","configuration"],"backgroundTag":"handler-init-failed","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"}