hashicorp/nomad · error

misconfigured connection

Error message

misconfigured connection

What it means

Sentinel-style error from snapshotSaveRequest when the Nomad agent has neither a server nor a client running, so no StreamingRpcHandler for Operator.SnapshotSave can be obtained; the agent is in a state where snapshots are impossible.

Source

Thrown at command/agent/operator_endpoint.go:372

	}

}

func (s *HTTPServer) snapshotSaveRequest(resp http.ResponseWriter, req *http.Request) (any, error) {
	args := &structs.SnapshotSaveRequest{}
	if s.parse(resp, req, &args.Region, &args.QueryOptions) {
		return nil, nil
	}

	var handler structs.StreamingRpcHandler
	var handlerErr error

	if server := s.agent.Server(); server != nil {
		handler, handlerErr = server.StreamingRpcHandler("Operator.SnapshotSave")
	} else if client := s.agent.Client(); client != nil {
		handler, handlerErr = client.RemoteStreamingRpcHandler("Operator.SnapshotSave")
	} else {
		handlerErr = fmt.Errorf("misconfigured connection")
	}

	if handlerErr != nil {
		return nil, CodedError(500, handlerErr.Error())
	}

	httpPipe, handlerPipe := net.Pipe()
	decoder := codec.NewDecoder(httpPipe, structs.MsgpackHandle)
	encoder := codec.NewEncoder(httpPipe, structs.MsgpackHandle)

	// Create a goroutine that closes the pipe if the connection closes.
	ctx, cancel := context.WithCancel(req.Context())
	defer cancel()
	go func() {
		<-ctx.Done()
		httpPipe.Close()
	}()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run the snapshot request against an agent running as a server or client, not a bare agent
2. Verify the agent configuration starts the server or client role
3. Point the CLI at the correct agent address

When it happens

Trigger: Thrown at command/agent/operator_endpoint.go:372 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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