{"record":{"id":"2d080186cdd3b2ce","repo":"hashicorp/nomad","slug":"unknown-rpc-method","errorCode":null,"errorMessage":"Unknown rpc method","messagePattern":"Unknown rpc method","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":62,"sourceCode":"\terrDeploymentTerminalNoPromote   = \"can't promote terminal deployment\"\n\terrDeploymentTerminalNoResume    = \"can't resume terminal deployment\"\n\terrDeploymentTerminalNoUnblock   = \"can't unblock terminal deployment\"\n\terrDeploymentTerminalNoRun       = \"can't run terminal deployment\"\n\terrDeploymentTerminalNoSetHealth = \"can't set health of allocations for a terminal deployment\"\n\terrDeploymentRunningNoUnblock    = \"can't unblock running deployment\"\n)\n\nvar (\n\tErrNoLeader                   = errors.New(errNoLeader)\n\tErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)\n\tErrNoRegionPath               = errors.New(errNoRegionPath)\n\tErrTokenNotFound              = errors.New(errTokenNotFound)\n\tErrTokenExpired               = errors.New(errTokenExpired)\n\tErrTokenInvalid               = errors.New(errTokenInvalid)\n\tErrPermissionDenied           = errors.New(errPermissionDenied)\n\tErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)\n\tErrNoNodeConn                 = errors.New(errNoNodeConn)\n\tErrUnknownMethod              = errors.New(errUnknownMethod)\n\tErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)\n\tErrNodeLacksRpc               = errors.New(errNodeLacksRpc)\n\tErrMissingAllocID             = errors.New(errMissingAllocID)\n\tErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)\n\tErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)\n\n\t// ErrResultPaginatorCreation is returned by list RPC handlers when the\n\t// result paginator cannot be built, for example when the server cannot\n\t// evaluate a requested filter expression. api.ResultPaginatorErrorContent\n\t// duplicates its message so the CLI can match it without importing structs.\n\t// Keep the two in sync.\n\tErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)\n\n\tErrUnknownNode = errors.New(ErrUnknownNodePrefix)\n\n\tErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)\n\tErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)\n\tErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L44-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the RPC method string to a registered endpoint name (check structs/rpc method constants and the server's mux table).","Verify client and server Nomad versions match and the endpoint exists in that release.","If routing custom methods, confirm the handler is registered with the RPC mux before serving.","Check the connection targets the right agent (client vs server) for the method being called."],"exampleFix":"// before\nerr := client.RPC(\"Bogus.Method\", args, &resp)\n// after\nerr := client.RPC(\"Node.Status\", args, &resp)","handlingStrategy":"type-guard","validationCode":"if method == \"\" || !registeredMethods[method] { return fmt.Errorf(\"unknown RPC method: %q\", method) }","typeGuard":"func IsErrUnknownMethod(err error) bool { return err != nil && strings.Contains(err.Error(), structs.ErrUnknownMethod.Error()) }","tryCatchPattern":"resp := new(structs.NodeClientStatsResponse)\nif err := client.RPC(method, args, resp); err != nil {\n    if structs.IsErrUnknownMethod(err) {\n        return fmt.Errorf(\"endpoint %s unavailable on this agent: %w\", method, err)\n    }\n    return err\n}","preventionTips":["Centralize RPC method names as constants instead of raw strings","Pin client and server to compatible Nomad versions","Enumerate registered endpoints when adding custom handlers","Write a smoke test per method name used in production code"],"tags":["rpc","nomad","method-not-found"],"backgroundTag":"rpc-method-not-found","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}