hashicorp/nomad · critical

failed to create deployment watcher: %v

Error message

failed to create deployment watcher: %v

What it means

NewServer wraps any error from setupDeploymentWatcher, which constructs the deployment watcher that tracks deployments and feeds them to the deployment watcher RPC endpoints. If the watcher cannot be created, the server cannot start and NewServer returns nil.

Source

Thrown at nomad/server.go:518

	}

	// Initialize the scheduling workers
	if err := s.setupWorkers(s.shutdownCtx); err != nil {
		s.Shutdown()
		s.logger.Error("failed to start workers", "error", err)
		return nil, fmt.Errorf("Failed to start workers: %v", err)
	}

	// Setup the Consul syncer
	if err := s.setupConsulSyncer(); err != nil {
		s.logger.Error("failed to create server consul syncer", "error", err)
		return nil, fmt.Errorf("failed to create server Consul syncer: %v", err)
	}

	// Setup the deployment watcher.
	if err := s.setupDeploymentWatcher(); err != nil {
		s.logger.Error("failed to create deployment watcher", "error", err)
		return nil, fmt.Errorf("failed to create deployment watcher: %v", err)
	}

	// Setup the volume watcher
	if err := s.setupVolumeWatcher(); err != nil {
		s.logger.Error("failed to create volume watcher", "error", err)
		return nil, fmt.Errorf("failed to create volume watcher: %v", err)
	}
	s.volumeControllerFutures = map[string]context.Context{}

	// Start the eval broker notification system so any subscribers can get
	// updates when the processes SetEnabled is triggered.
	go s.evalBroker.enabledNotifier.Run()

	// Setup the node drainer.
	s.setupNodeDrainer()

	// Setup the enterprise state
	if err := s.setupEnterprise(config); err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the 'failed to create deployment watcher' log line above the error for the inner cause.
2. Confirm server configuration is valid (validate with `nomad agent -config ... -verify-only` if available).
3. Check host memory/CPU limits; retry server startup after freeing resources.
4. Upgrade/reinstall Nomad if the failure persists with known-good config.

srv, err := nomad.NewServer(cfg, logger)
if err != nil && strings.Contains(err.Error(), "failed to create deployment watcher") {
    logger.Error("deployment watcher init failed; check resources and config", "err", err)
    return err
}

When it happens

Trigger: NewServer with a config that makes setupDeploymentWatcher fail — typically the internal deployment watcher cannot be initialized (e.g. queue/eval broker setup issues or invalid config values used when constructing the watcher).

Common situations: Rare in practice; seen when Nomad binaries are miscompiled/partially initialized, when memory limits kill internal components during server bring-up, or when a plugin/config-dependent component the watcher relies on fails early in NewServer.

Related errors

• server config setup failed: %s
• server setup failed: %v
• rpc.dial_timeout must be greater than or equal to zero
• client_introduction.enforcement must be set
• No addresses found, please configure one.

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/63992ca630b9d134. Report an issue: GitHub.