Config check reference

Every problem that nocleye check can report, with what to do about it. Errors stop the gateway from starting. Warnings don’t, but point to something you probably want to fix.

Errors

File and format

Message	Fix
Config file is empty	Add your configuration, starting with ApiVersion.
Invalid YAML syntax	Check indentation (spaces only, no tabs), colons and quotes around the reported line.
Unknown key “…”	Check the spelling, keys are case sensitive, or remove it.
Wrong kind of value	The key expects a different kind of value, e.g. a list or a number. The message says which.
Unsupported ApiVersion	Set ApiVersion to v1Beta.
No servers defined	Add at least one server under ServerConfigs.
No routes defined	Add at least one route under ServerRoutes.

Servers and routes

Message	Fix
Server without a URL	Set the URL the gateway should forward requests to, e.g. http://localhost:9090.
Server with an invalid URL	Use a full URL including the scheme, e.g. http://localhost:9090.
Server TLS CA certificate can’t be used	Check that TLS.CACertFile points to a readable PEM certificate file.
Route without a PathPattern	Set the path the route should match, e.g. /api/users.
Route targets a server that doesn’t exist	Set TargetServer to a name defined under ServerConfigs.
Two routes use the same PathPattern	Give each route its own PathPattern, or remove the duplicate.

Header rules

Message	Fix
Invalid header collection mode	Set the header rule Mode to All or Custom.
Invalid header name in a header rule	Header names can’t be empty or contain underscores or other invalid characters, e.g. X-Trace-Id.
Reserved header used in a header rule	That header is managed by the gateway, pick another name.
Server / Route / GlobalConfig uses a header rule that doesn’t exist	Define the rule under Rules > HeaderRules, or fix the name.

Client ID rules

Message	Fix
Unknown client id collection mode	Use one of the client ID modes.
Custom header rule without a value	Set HeaderCustomValue, or change the mode.
Custom query string rule without a value	Set QueryStringCustomValue, or change the mode.
Server / Route / GlobalConfig uses a client id rule that doesn’t exist	Define the rule under Rules > ClientIDRules, or fix the name.

Usage control rules

Message	Fix
Usage control rule with an invalid request count	RequestCount must be greater than zero.
Unrecognised time window format	Use a number followed by a unit: m (minutes), h (hours), w (weeks) or Mo (months), e.g. 1m, 5h, 1w, 1Mo.
Invalid time window	Use a positive number followed by a unit, e.g. 1m, 5h, 1w, 1Mo.
Server / Route / GlobalConfig uses a usage control rule that doesn’t exist	Define the rule under Rules > UsageControlRules, or fix the name.

Authentication

Message	Fix
Unknown auth method mode	Mode must be Bearer or RawHeader.
Unsupported signing method	SigningMethod must be one of HS256, HS384, HS512, RS256, ES256 or EdDSA.
Auth method without a KeyRef	Set KeyRef to the key the gateway should use to verify tokens.
Auth method without a HeaderName	RawHeader mode reads the token from a header, set HeaderName.
Server / Route / GlobalConfig uses an auth method that doesn’t exist	Define it under AuthMethods, or fix the name.

Command line flags

Message	Fix
Support port collides with the gateway port	Set --sPort (or SUPPORT_PORT) to a port different from --gPort.
Invalid Prometheus metrics list	Use all, leave it empty, or list metric families.

Check could not run

Message	Meaning
No config file was given	Pass --gConfigPath <file> or set GATEWAY_CONFIG_PATH. The check can’t run.
The config file doesn’t exist, can’t be read, or is a directory	Fix the path. The check can’t run.

Warnings

Message	What it means and what to do
No usage control rules defined	Clients won’t be limited at all. Add a rule under Rules > UsageControlRules if you want limits.
No auth method defined	Every route is publicly accessible. Add an entry under AuthMethods if you need protection.
Requests without a token are let through	Set RefuseOnMissing to true to reject them.
Requests with an expired token are let through	Set RefuseOnExpired to true to reject them.
Server is unreachable	No route targets this server. Add a route for it or remove the server.
Server TLS settings are ignored	The URL doesn’t use https, so the TLS block has no effect. Switch to https or remove the block.
Server certificate verification is disabled	InsecureSkipVerify makes the connection open to impersonation. Prefer TLS.CACertFile.
No client id rules defined	Clients will be identified by IP. Add a rule under Rules > ClientIDRules to use something else.
No header rules defined	All headers from the request are forwarded. Add a rule under Rules > HeaderRules to restrict them.
Prometheus enabled with no metrics selected	/metrics will answer with no series. Set --sPrometheusMetrics, or leave Prometheus disabled.
Support server is not loopback and has no token	The live config API is open to anyone who can reach the support server. Set --sToken (or SUPPORT_TOKEN), or bind --sHost to loopback. See Support server.