hashicorp/nomad · error

Unknown rpc method

Error message

Unknown rpc method

What it means

ErrUnknownMethod is a sentinel error thrown when an RPC request names a method for which no handler is registered. The Nomad server/router looks up the endpoint by the method string (e.g. "Bogus.Method") and, finding none, returns this error to the caller. It signals a client/server method-name mismatch, not a transport or permissions problem.

Source

Thrown at nomad/structs/errors.go:62

	errDeploymentTerminalNoPromote   = "can't promote terminal deployment"
	errDeploymentTerminalNoResume    = "can't resume terminal deployment"
	errDeploymentTerminalNoUnblock   = "can't unblock terminal deployment"
	errDeploymentTerminalNoRun       = "can't run terminal deployment"
	errDeploymentTerminalNoSetHealth = "can't set health of allocations for a terminal deployment"
	errDeploymentRunningNoUnblock    = "can't unblock running deployment"
)

var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrNoRegionPath               = errors.New(errNoRegionPath)
	ErrTokenNotFound              = errors.New(errTokenNotFound)
	ErrTokenExpired               = errors.New(errTokenExpired)
	ErrTokenInvalid               = errors.New(errTokenInvalid)
	ErrPermissionDenied           = errors.New(errPermissionDenied)
	ErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)
	ErrNoNodeConn                 = errors.New(errNoNodeConn)
	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

	ErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)
	ErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)
	ErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Correct the RPC method string to a registered endpoint name (check structs/rpc method constants and the server's mux table).
  2. Verify client and server Nomad versions match and the endpoint exists in that release.
  3. If routing custom methods, confirm the handler is registered with the RPC mux before serving.
  4. Check the connection targets the right agent (client vs server) for the method being called.

Example fix

// before
err := client.RPC("Bogus.Method", args, &resp)
// after
err := client.RPC("Node.Status", args, &resp)
Defensive patterns

Strategy: type-guard

Validate before calling

if method == "" || !registeredMethods[method] { return fmt.Errorf("unknown RPC method: %q", method) }

Type guard

func IsErrUnknownMethod(err error) bool { return err != nil && strings.Contains(err.Error(), structs.ErrUnknownMethod.Error()) }

Try / catch

resp := new(structs.NodeClientStatsResponse)
if err := client.RPC(method, args, resp); err != nil {
    if structs.IsErrUnknownMethod(err) {
        return fmt.Errorf("endpoint %s unavailable on this agent: %w", method, err)
    }
    return err
}

Prevention

When it happens

Trigger: Calling an RPC with a misspelled or nonexistent method name (e.g. "Bogus" in the tests); calling a method on an endpoint the server version does not register; using a streaming/multiplex V2 path whose handler is not implemented; GetHandler failing to resolve the method in the RPC router.

Common situations: Typo in the method string passed to an RPC client; client built against a newer Nomad than the server (method doesn't exist yet); hitting node-only endpoints through the wrong connection; custom plugins registering endpoints under unexpected names.

Related errors

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