weaviate/weaviate · critical

cannot init handler: %w

Error message

cannot init handler: %w

What it means

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.

Source

Thrown at usecases/schema/manager.go:232

	cloud modulecapabilities.OffloadCloud,
	parser Parser,
	collectionRetrievalStrategyFF *configRuntime.FeatureFlag[string],
	namespacesExister namespaces.Exister,
	dropVectorEnqueuer DropVectorIndexEnqueuer,
) (*Manager, error) {
	handler, err := NewHandler(
		schemaReader,
		schemaManager,
		validator,
		logger, authorizer,
		schemaConfig,
		config, configParser, vectorizerValidator, invertedConfigValidator,
		moduleConfig, clusterState, cloud, parser, NewClassGetter(&parser, schemaManager, schemaReader, collectionRetrievalStrategyFF, logger),
		namespacesExister,
		dropVectorEnqueuer,
	)
	if err != nil {
		return nil, fmt.Errorf("cannot init handler: %w", err)
	}
	m := &Manager{
		validator:    validator,
		repo:         repo,
		logger:       logger,
		clusterState: clusterState,
		Handler:      handler,
		SchemaReader: schemaReader,
		Authorizer:   authorizer,
	}

	return m, nil
}

func (m *Manager) ClusterHealthScore() int {
	return m.clusterState.ClusterHealthScore()
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the wrapped cause after 'cannot init handler:' — it names the exact subsystem that failed
2. Check PERSISTENCE_DATA_PATH exists, is writable, and its schema data is compatible with this Weaviate version
3. Review recent release notes for breaking schema/config migrations when upgrading versions
4. Validate module configs (vectorizers, moduleConfig) in the environment and class definitions

// pre-start checks: writable data dir and version-compatible schema files
if err := fsx.EnsureWritable(persistenceDataPath); err != nil { log.Fatal(err) }

appState, err := MakeAppState(...)
if err != nil {
    if strings.Contains(err.Error(), "cannot init handler") {
        log.Fatalf("schema handler init failed: %v", err) // surface wrapped cause
    }
    log.Fatal(err)
}

When it happens

Trigger: 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.

Common situations: Upgrading Weaviate onto incompatible existing persistence data; PERSISTENCE_DATA_PATH unwritable; corrupted schema files; misconfigured modules referenced in the schema (missing vectorizer config).

Related errors

• init %s
• init vectorizer
• init cross encoder
• can't create the default handler, as no api is set
• no workers to add batch-jobs configured.

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/97f8745061ebb1ac. Report an issue: GitHub.