Diagnostic rules

Every finding is a rule with a stable id, a default severity and a source that says how well founded it is. There are 36 today. This page mirrors docs/rules.md, which the repository generates from the code.

Sources

The source is shown in the message whenever a rule is not the documented language, so a quirk of RouterOS 7.21.4 is never presented as the specification.

Where the documentation and the device disagree, the device decides what is an error — a script that fails to compile — and the documentation decides what is merely reported as a warning. The register ids point to rows of ambiguities.md, the evidence for each rule.

Severities

• errorA script that fails to compile on RouterOS. 28 rules.
• warningRouterOS accepts it, or the finding depends on your hardware's command list. 8 rules.
• information · hintAvailable when you set a severity yourself; no rule defaults to them.
• offSwitches the rule off.

Change one with the severities setting, or --severity RULE=LEVEL on the command line. See Configuration.

All rules

• schema/ambiguous-name
  error
  device
  An abbreviated name that matches more than one menu, command or parameter.register C-10
• schema/duplicate-parameter
  error
  device
  The same parameter given twice.
  Example

  /ip address add address=10.0.0.1/24 address=10.0.1.1/24 interface=ether1

  error'address' is given more than once. (RouterOS behaviour that the documentation does not describe)

• schema/flag-with-value
  error
  device
  A flag such as detail or count-only written as name=value.
• schema/missing-required
  error
  device
  A parameter that the command cannot be compiled without is missing.
  Example

  /ip address add address=192.168.88.2/24

  errorMissing a value for interface. (RouterOS behaviour that the documentation does not describe)

• schema/parameter-needs-value
  error
  device
  A parameter that takes a value written without one, as if it were a flag.
  Example

  /ip address add address=10.0.0.1/24 interface=ether1 comment

  error'comment' takes a value: write comment=... (RouterOS behaviour that the documentation does not describe)

• schema/unexpected-argument
  error
  device
  More unnamed arguments than the command takes.register C-04
  Example

  /ip firewall nat add chain=srcnat action=masquerade # WAN

  errorThis command takes no unnamed arguments, and a '#' only starts a comment at the beginning of a command, so RouterOS reads this as an argument. Put ';' before the comment. (RouterOS behaviour that the documentation does not describe)

• schema/unknown-command
  warning
  device
  A menu or command that is not in the command database. Menus of packages the database was not generated with are missing from it.register C-02, C-10, P-01, P-02
  Example

  /ip firewall filtr add chain=input action=drop

  warning'filtr' is not a menu or command in /ip firewall of the RouterOS 7.21.4 command database. Did you mean 'filter'? (RouterOS behaviour that the documentation does not describe)

• schema/unknown-parameter
  warning
  device
  A parameter that the command does not have in the command database. Some parameters exist only on some hardware.register C-10
  Example

  /ip address add adress=192.168.88.2/24 interface=ether1

  warning'adress' is not a parameter of this command in the RouterOS 7.21.4 command database. Did you mean 'address'? (RouterOS behaviour that the documentation does not describe)

• syntax/adjacent-tokens
  error
  device
  Two values written with no space between them.register L-10, L-16
• syntax/bad-interpolation
  error
  doc
  A "$" inside a string that is not followed by a variable name, "(" or "[".
• syntax/bare-dollar
  error
  device
  A "$" that is not followed by a variable name.
• syntax/bom
  error
  device
  A byte order mark at the start of the file is rejected by RouterOS.register L-06
• syntax/dollar-expression-outside-string
  error
  device
  "$(" and "$[" are only valid inside a string.register O-09
• syntax/empty-expression
  error
  device
  An empty "( )".
• syntax/expected-command
  error
  doc
  A prefix such as ":" with no command after it, or a line that starts with something that cannot be a command.
• syntax/expected-operand
  error
  device
  An operator without the value it needs.
• syntax/invalid-character
  error
  device
  A character that RouterOS does not accept outside a string.register L-15, L-16
• syntax/invalid-escape
  error
  doc
  Backslash followed by something that is not a documented escape sequence.register E-03, E-04
• syntax/missing-closer
  error
  doc
  A "(", "[" or "{" is never closed.
• syntax/missing-separator
  error
  device
  Two commands on one line without ";" between them.register L-11
• syntax/newline-in-parens
  error
  device
  A line break inside "( )" without a backslash.
• syntax/space-before-equals
  error
  doc
  Whitespace before "=" in a parameter.register L-09
• syntax/statement-starts-with-pair
  error
  device
  A command line that starts with name=value, for example "else=" on its own line.register C-12, A-01
• syntax/stray-backslash
  warning
  open
  A backslash outside a string that does not end the line. The documentation calls it illegal; RouterOS ignores it.register L-03
• syntax/stray-closer
  warning
  open
  A "}" or "]" without a matching opener. RouterOS accepts it.register L-13
• syntax/too-deeply-nested
  error
  open
  Brackets nested deeper than the parser follows.
• syntax/trailing-comment
  warning
  device
  A "#" after the first word of a command is an argument, not a comment. With a command database the surplus arguments are reported as errors by schema/unexpected-argument.register L-01
• syntax/unexpected-closer
  error
  device
  A ")" without a matching "(".
• syntax/unexpected-equals
  error
  device
  An "=" that does not belong to a parameter.register L-16
• syntax/unexpected-token
  error
  device
  A token that cannot appear inside an expression.
• syntax/unterminated-string
  error
  doc
  A string literal is not closed.
• vars/invalid-name
  error
  device
  A variable name with characters other than letters and digits, written without quotes, or with a "$" where it is declared.register V-07
  Example

  :local my-var 1

  errorA variable name written without quotes may only contain letters and digits, not '-'. Quote the name: "my-var". (RouterOS behaviour that the documentation does not describe)

• vars/keyword-name
  warning
  doc
  A variable named and, or or in. The documentation reserves them; RouterOS accepts them.register V-08
• vars/local-out-of-scope
  warning
  device
  A local variable is read where its scope has ended, for example on a later top-level line of an imported file.register V-03
  Example

  :local gw 192.168.88.1
  /ip route add gateway=$gw

  warning$gw is a local variable of an earlier line or of a block that has ended, so it is empty here (an imported file gives every line its own scope). Use ':global gw' or put the commands in one { } block. (RouterOS behaviour that the documentation does not describe)

• vars/set-undeclared
  error
  device
  :set of a variable that is not declared in the same or an enclosing block.register V-01, V-03, V-04
  Example

  :local count 0
  :set count 1

  error':set count' needs 'count' to be declared first, with ':local count' or ':global count' earlier in the same block or in a block around it. 'count' is declared elsewhere in this file, but each line of an imported file is its own scope and a block that has ended hides its names. Declare it again here or put the commands in one { } block. (RouterOS behaviour that the documentation does not describe)

• vars/undeclared-read
  warning
  doc
  A variable is read but never declared in the file. RouterOS reads it as empty.register V-01, V-14
  Example

  :put $custom

  warning$custom is not declared in this file. The documentation requires a declaration before use; RouterOS 7.21.4 reads an undeclared variable as empty. Declare it with ':local custom' or ':global custom', or list it under "contextVariables" if RouterOS provides it.

No rule matches. Try a shorter search or clear a filter.