gofr-dev/gofr · error

endpoint must specify requiredPermissions (or be public)

Error message

endpoint must specify requiredPermissions (or be public)

What it means

ErrEndpointMissingPermissions is returned by validate and storeEndpointMapping in the RBAC package when a registered endpoint neither declares requiredPermissions nor is marked public. RBAC is config-pure: every protected route must state which roles/permissions it needs or explicitly opt out as public, otherwise the framework cannot decide access. It is exported so callers can compare with errors.Is.

Source

Thrown at pkg/gofr/rbac/config.go:25

	"net/http"
	"os"
	"path/filepath"
	"strings"

	"github.com/gorilla/mux"
	"go.opentelemetry.io/otel/trace"
	"gopkg.in/yaml.v3"

	"gofr.dev/pkg/gofr/container"
	"gofr.dev/pkg/gofr/datasource"
)

var (
	// errUnsupportedFormat is returned when the config file format is not supported.
	errUnsupportedFormat = errors.New("unsupported config file format")

	// ErrEndpointMissingPermissions is returned when an endpoint doesn't specify requiredPermissions and is not public.
	ErrEndpointMissingPermissions = errors.New("endpoint must specify requiredPermissions (or be public)")

	// errWildcardPatternNotSupported is returned when a wildcard pattern is used.
	errWildcardPatternNotSupported = errors.New("wildcard pattern '/*' is not supported, use mux patterns instead")

	// errRegexPatternNotSupported is returned when an old regex pattern is used.
	errRegexPatternNotSupported = errors.New("regex pattern '^...$' is not supported, use mux patterns instead")

	// errRegexIndicatorNotSupported is returned when regex indicators are used outside variable constraints.
	errRegexIndicatorNotSupported = errors.New("regex pattern is not supported, use mux patterns instead")
)

// RoleDefinition defines a role with its permissions and inheritance.
// Pure config-based: only role->permission mapping is supported.
type RoleDefinition struct {
	// Name is the role name (required)
	Name string `json:"name" yaml:"name"`

	// Permissions is a list of permissions for this role (format: "resource:action")

View on GitHub (pinned to 187eb24962)

Solutions

1. Add requiredPermissions to the endpoint definition listing the needed roles/permissions.
2. If the endpoint should be open, explicitly mark it public in the endpoint config.
3. Audit all registered endpoints (walk route registrations) to find those missing requiredPermissions.
4. Compare with errors.Is(err, rbac.ErrEndpointMissingPermissions) in startup validation to fail fast with a clear message.

Example fix

// before
router.Get("/admin/stats", statsHandler) // no permissions declared
// after
router.Get("/admin/stats", statsHandler,
	rbac.WithRequiredPermissions("admin", "stats:read"))

func assertEndpointAuthorized(ep Endpoint) error {
	if ep.Public || len(ep.RequiredPermissions) > 0 {
		return nil
	}
	return rbac.ErrEndpointMissingPermissions
}

func endpointIsCovered(ep Endpoint) bool {
	return ep.Public || len(ep.RequiredPermissions) > 0
}

if err := validate(cfg); err != nil {
	if errors.Is(err, rbac.ErrEndpointMissingPermissions) {
		log.Fatalf("endpoint missing requiredPermissions (or public flag): %v", err)
	}
	return err
}

When it happens

Trigger: Registering an HTTP route (e.g. via router/route registration while RBAC is enabled) whose endpoint definition omits requiredPermissions and does not set public: true.

Common situations: Adding a new handler and forgetting the permissions block; migrating from an open endpoint behind a newly enabled RBAC; copy-pasting endpoint config from a public route without adjusting.

Related errors

• unsupported config file format
• wildcard pattern '/*' is not supported, use mux patterns ins
• regex pattern '^...$' is not supported, use mux patterns ins
• regex pattern is not supported, use mux patterns instead
• failed to read RBAC config file %s: %w

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/3ff17f0bd8e708f9. Report an issue: GitHub.