Check Rules
nginx-ui plugin lint and nginx-ui plugin conformance report every problem with the name of the rule it breaks. This page explains each rule and links to the part of the guide it comes from.
- lint rules are checked from the files of aplugin directory or package. An error stops the package from installing; a warning points at a problem the person installing the plugin will notice.
- conformance rules are checked by running theplugin. A case passes, fails, or is skipped when it does not apply.
Manifest
manifest-json
lint errorplugin.json is missing or is not a single JSON object. See Manifest.
manifest-id
lint errorid is missing, longer than 64 characters or not a dotted lowercase id such as io.github.example.mydns. See Naming.
manifest-name
lint errorname is missing or empty.
manifest-version
lint errorversion is missing or not a semantic version.
manifest-api-version
lint errorapi_version is missing or is not the protocol generation Nginx UI implements. See Versions and Compatibility.
manifest-parts
lint errorThe manifest declares none of server, webapp and content, so the plugin would install nothing.
manifest-icon
lint erroricon_path is not a safe relative path.
manifest-i18n
lint error warningError when an i18n key is not a language code such as zh_CN; warning when the Nginx UI running the linter does not have the language, which it then shows in English. See Manifest.
manifest-requires
lint errorAn entry of requires has an invalid plugin id. See Dependencies and Conflicts.
manifest-conflicts
lint errorAn entry of conflicts is not a valid plugin id, is the plugin's own id, is listed twice or is also in requires. See Dependencies and Conflicts.
manifest-permissions
lint error warningAn unknown permission is an error, a permission listed twice a warning. See Permissions and Security.
manifest-permission-reasons
lint errorA key of permission_reasons, or of its translation in i18n, is not one of permissions, or its reason is longer than 300 characters. See Explaining Permissions.
manifest-screenshots
lint errorscreenshots lists more than eight images; an id is missing, malformed or used twice; a path is missing, is not a safe relative path, is not a PNG, JPEG or WebP image or is listed twice; a caption is longer than 200 characters; or a key of screenshot_captions in i18n is not the id of a screenshot. See Screenshots.
capability-name
lint errorA capability name is not one Nginx UI knows. See Manifest.
capability-duplicate
lint errorA capability is listed twice.
server-entry
lint errorserver has neither executables nor command. See Server Process.
server-command
lint errorThe first element of server.command is empty.
server-lifecycle
lint errorserver.lifecycle is not resident or on_demand.
server-idle-timeout
lint errorserver.idle_timeout_seconds is negative.
server-paths
lint error warningError when an executable path, or the first element of command when it contains a separator, is not a safe relative path. Warning when the program command names is not found on PATH of the machine running the linter.
server-resources
lint errorA value of server.resources is negative. See Resources.
settings-key
lint errorA settings field has no key, or two fields share one. See Settings.
settings-type
lint error warningError for an unknown field type or a list default that is not a list of strings; warning for a default that does not fit its type.
settings-options
lint errorA select field has no options.
event-permission
lint warninglog.paths_changed is subscribed without the log.files permission, so it is never delivered. See Host API.
reserved-namespace
lint warningThe id uses com.nginxui.*, which is reserved for the Nginx UI project. See Naming.
network-permission
lint warningA capability that talks to a vendor or target is declared without the network permission. See Permissions and Security.
unused-permission
lint warningA permission is requested that only a capability the plugin does not declare would use, such as mcp without the mcp capability.
Package
package-file-name
lint warningThe package file name names another id or version than its manifest. See Naming.
package-layout
lint errorplugin.json is neither at the root of the archive nor one directory down, or the archive cannot be read. See Packaging.
package-paths
lint errorAn archive entry is not a safe relative path.
package-links
lint errorThe archive contains a symbolic or hard link.
package-escape
lint errorAn entry would be extracted outside the plugin directory.
package-entries
lint errorThe package has more than 10,000 entries. See Limits.
package-size
lint errorThe files of the package exceed 256 MiB uncompressed.
package-docs
lint error warningError when README.md is missing; warning when LICENSE is missing, or when the readme lacks a section it should have. See Packaging.
package-executables
lint error warningError when a file server.executables or server.command declares is missing or not a regular file; warning when it lacks the executable bit. See Executables.
package-platform
lint errorA per-platform package does not declare exactly its own platform in server.executables. See Per-Platform Packages.
Signature
signature-sums
lint errorplugin.sums does not follow the required format. See Signing by Hand.
signature-files
lint warningOnly one of plugin.sums and plugin.sums.minisig is present, so the package counts as unsigned.
signature-mismatch
lint errorplugin.sums does not match the files: a listed file is missing or has another SHA-256, or a file is not listed. The package changed after signing and will never install. See How Nginx UI Checks a Package.
signature-signer
lint warningThe signature does not verify with a key the linter knows: the official plugin key of the project, or a partner key with a valid certificate in the package. This is expected for a community plugin, whose key only a catalog or an operator names. See Trust Levels.
partner-files
lint warningOnly one of plugin.partner and plugin.partner.minisig is present, so the package carries no partner certificate. See Partner Plugins.
partner-comment
lint warningThe partner certificate does not verify: plugin.partner is not a public key, the official plugin key did not sign it, or the trusted comment has the wrong format.
partner-certificate
lint warningThe partner certificate has expired, or plugin.sums.minisig is not signed by the key the certificate names, so the certificate gives the package nothing.
signer-files
lint warningOnly one of plugin.signer and plugin.signer.minisig is in the package, so the signer certificate is ignored. See Signing Keys.
signer-certificate
lint warningThe signer certificate does not parse, its trusted comment does not name the plugin of the package, or plugin.sums.minisig is not signed by the key the certificate names, so the certificate gives the package nothing. The linter does not know the primary key, so the catalog and Nginx UI check who issued the certificate. See Signing Keys.
Protocol and Lifecycle
protocol-stderr
conformanceThe plugin writes its logs to standard error. See Protocol.
protocol-notification
conformanceA notification of an unknown method gets no answer and the connection stays usable. See Messages.
protocol-concurrency
conformance20 concurrent plugin.ping calls are all answered.
protocol-errors
conformanceA method the plugin does not have answers -32601, and malformed parameters answer -32602 or -32000 instead of hanging. See Error Codes.
protocol-grpc
conformanceThe gRPC endpoint the plugin reports accepts a connection and answers plugin.ping. See gRPC Transport.
protocol-transports
conformanceThe same call gives the same result or error over standard input and output and over gRPC. Runs when both transports were tested.
lifecycle-handshake
conformanceThe handshake completes within its time limit. See Lifecycle.
lifecycle-api-version
conformanceThe handshake reports the protocol generation Nginx UI implements.
lifecycle-capabilities
conformanceThe handshake reports exactly the capabilities of the manifest.
lifecycle-ping
conformanceplugin.ping is answered. See Health Checks.
lifecycle-shutdown
conformanceplugin.shutdown and plugin.exit stop the process in time. See Stopping.
Web Interface
webapp-paths
lint errorwebapp.bundle_path or webapp.style_path is not a safe relative path. See Browser Bundle.
webapp-pages
lint errorA page has no path, or its file is not a safe relative path. See Static Pages.
webapp-chunks
lint errorwebapp.chunks is present without bundle_path, or a chunk has an invalid name or path, points at the bundle itself, shares a path with another chunk or names a missing file. See Chunks.
webapp-bundle
lint conformanceThe bundle file exists and is a script Nginx UI can load. See Building.
webapp-register
conformanceThe bundle registers itself with the manifest id. See Registering the Plugin.
webapp-chunk-files
lint conformanceError when a chunk file is empty or missing; warning when it lies outside the directory Nginx UI serves the bundle from.
DNS-01
dns01-block
lint errorThe dns01 capability is declared without providers. See DNS-01.
dns01-code
lint errorA provider code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
dns01-name
lint errorA provider has no name.
dns01-form
lint errorA provider has no form, or the form breaks a rule of the Credential Form: a field without a key or label, a duplicate key, an unknown group or unit, a single sign in method, duplicate method names, a method listing a field that is not a credential, a misused values key, two identical methods or more than one recommended method.
dns01-present
conformancedns01.present answers for the first provider.
dns01-validate
conformancedns01.validate with an empty configuration answers as expected.
dns01-options
conformancedns01.options answers, or answers -32002.
dns01-check
conformancedns01.check answers, or answers -32002.
HTTP Endpoints
http-block
lint errorThe http capability is declared without an http block, or listen is not unix or rpc. See HTTP Endpoints.
Configuration Forms
configuration-fields
lint errorA field of a configuration form has no key, a duplicate key, an unknown type or no display_name. See Configuration Form.
Notification Channels
notify-block
lint errorThe notify capability is declared without channels. See Notification Channels.
notify-code
lint errorA channel code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
notify-name
lint errorA channel has no name.
notify-validate
conformancenotify.validate with an empty configuration answers -32003 naming a required field, or {} when the channel has none. notify.send is never called, since it would reach the service.
Health Checks
probe-block
lint errorThe probe capability is declared without kinds. See Health Checks.
probe-code
lint errorA kind code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
probe-kind
lint errorA kind has no name, or its configuration form is invalid.
probe-check
conformanceprobe.check of the first kind against an unreachable target answers in time.
probe-result
conformanceThe answer has a known status and a non-negative latency_ms, or is -32003 naming a field.
MCP Tools
mcp-block
lint errorThe mcp capability is declared without tools or without the mcp permission. See MCP Tools.
mcp-tool
lint errorA tool name does not match ^[a-z0-9][a-z0-9_-]{0,47}$, is declared twice, or the tool has no description.
mcp-input-schema
lint errorAn input_schema whose type is not object.
mcp-unknown-tool
conformanceCalling a tool the manifest does not declare answers -32602. No declared tool is called, since it may change state.
Storage
storage-block
lint errorThe storage capability is declared without backends. See Storage.
storage-code
lint errorA backend code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
storage-backend
lint errorA backend has no name, or its configuration form is invalid.
storage-list
conformancestorage.list with an empty configuration answers in time, with -32003 naming a required field or with a list. Nothing is stored, fetched or deleted.
storage-validate
conformancestorage.validate with an empty configuration answers -32003 naming a required field, or {}.
Certificate Deployment
deploy-block
lint errorThe cert.deploy capability is declared without targets or without the cert.deploy permission. See Certificate Deployment.
deploy-code
lint errorA target code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
deploy-target
lint errorA target has no name, or its configuration form is invalid.
deploy-dry-run
conformanceA dry run push of a throwaway certificate answers in time. A real push is never made.
deploy-validate
conformancedeploy.validate with an empty configuration answers -32003 naming a required field, or {}.
Blocklists
blocklist-block
lint errorThe security.blocklist capability is declared without sources or without the network permission. See Blocklists.
blocklist-code
lint errorA source code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
blocklist-source
lint errorA source has no name, an invalid configuration form, or a refresh_seconds between 1 and 59 or below 0.
blocklist-fetch
conformanceblocklist.fetch with an empty configuration answers in time with entries whose addresses parse.
blocklist-errors
conformanceA source that needs configuration answers -32003 naming the field instead of an empty list.
Upstream Discovery
discovery-block
lint errorThe upstream.discovery capability is declared without providers or without the network permission. See Upstream Discovery.
discovery-code
lint errorA provider code does not match ^[a-z0-9-]{2,32}$ or is declared twice.
discovery-provider
lint errorA provider has no name, or its configuration form is invalid.
discovery-resolve
conformancediscovery.resolve with an empty configuration answers in time with targets whose ports are between 1 and 65535.
discovery-errors
conformanceA provider that needs configuration, or an unknown service, answers -32003 naming the field.
Access Log Streaming
log-sink-permission
lint errorThe log.sink capability is declared without the log.read permission. See Access Log Streaming.
log-sink-block
lint warningA log_sink block without the log.sink capability, which has no effect.
log-sink-batch
lint errorbatch_size is outside 0 to 4096, or flush_interval_ms is between 1 and 49 or negative.
log-sink-formats
lint errorA format is not combined or raw, or is listed twice.
log-sink-transport
conformancelog.push sent over standard input and output answers -32601, and the plugin serves gRPC.
log-sink-push
conformanceA stream of three entries is answered in time with accepted 3. Skipped when only standard input and output are tested.
Templates and Translations
content-paths
lint errorcontent.templates or content.locales is not a safe relative path. See Templates and Translations.
content-without-server
lint errorA manifest without server declares capabilities, cron or events, which need a process.
content-templates
lint error warningError when the templates directory is missing, is not a directory or holds no template in conf/ or block/; warning for an entry that is not a template. See Templates.
content-template
lint error warningError when a template does not parse or render with its default values; warning when it has no name.
content-locales
lint error warningError when the locales directory is missing, holds no .po file or holds one whose name is not a language code; warning for a file of a language the Nginx UI running the linter does not have, and for other entries. See Translations.
content-locale
lint errorA translation file does not parse.