Troubleshooting

Your file did not load and you are staring at a code like AT207. This page is where you find the fix.

How errors surface

When alphaTab parses your file, it collects diagnostics in three bags — one from the lexer, one from the parser, and one from semantic analysis. On failure, alphaTab throws an AlphaTexErrorWithDiagnostics that carries every collected message. Depending on how you loaded the file, the diagnostics land in one of three places:

• Editor tooling (Monaco, VS Code): the language server surfaces each diagnostic as a red or yellow squiggle at the exact position in your source. Hover for the message.
• AlphaTabApi at runtime: subscribe to the error event. The error object exposes lexerDiagnostics, parserDiagnostics, and semanticDiagnostics — each is an AlphaTexDiagnosticBag.
• Browser console: with default settings, alphaTab logs every diagnostic through its Logger. Set logLevel to debug if you want the full trace.

Every message carries an AT-code. The code is the fastest lookup key — search this page for AT207, AT215, and so on.

Top failure modes

Most alphaTex files that fail to load trip one of these six patterns. Each shows the shape of the source that breaks, followed by the shape that works.

Unterminated string (AT006)

The lexer reached the end of the file while still inside a double-quoted string.

Broken

\title "Iron Waltz
\tempo 90

Fixed

\title "Iron Waltz"
\tempo 90

Close the quote. If the quote is intentional inside a title, escape it as \" or wrap the whole title in a different delimiter.

Fret note without string (AT207)

A number followed by a beat separator has no string number. Fret notation on a guitar staff needs both — write 12.2, not 12.

Broken

:4 12 14 15

Fixed

:4 12.2 14.2 15.2

Add .<string> after every fret. If you meant pitched notes instead, the file now needs a \staff prelude that declares pitched notation.

String number out of range (AT208)

The string number in fret.string is higher than the tuning declares. A six-string tuning caps out at .6.

Broken

\tuning e5 b4 g4 d4 a3 e3
:4 5.7

Fixed

\tuning e5 b4 g4 d4 a3 e3
:4 5.6

Check your \tuning length. Seven strings need seven pitches in \tuning; the string index is 1-based.

Note kind does not match the staff (AT215 / AT216 / AT218)

Pitched note values (c4, g#3, ...) land on a fretted staff, or fret.string values land on a pitched staff, or percussion articulations mix with either.

Broken

\track "Guitar"
:4 c4 e4 g4

Fixed

\track "Guitar"
\staff{ pitched }
:4 c4 e4 g4

Match the note syntax to the staff. Guitar tab uses fret.string; pitched staves use note names with octave; percussion uses the articulation name or number.

Bad color format (AT213)

Colors accept #RRGGBB, #RRGGBBAA, rgb(...), rgba(...), or a named color. Anything else fails.

Broken

\track "Lead" { color "bright-red" }

Fixed

\track "Lead" { color "#ff3333" }

Convert your color to hex or use one of the named CSS colors.

Legacy argument shapes (AT301 / AT303)

alphaTex 1.7 wraps multi-value arguments in parentheses. Older sources that list values bare still parse, but the warning fires until you upgrade the source.

Warns

\ts 3 4

Clean

\ts (3 4)

The same shape applies to any metadata tag or property that takes more than one value.

For the full list — every code the lexer and parser can raise, its raw message template, and its severity — see the categories below.

Every diagnostic code

Writing errors

These fire while alphaTab is still reading the raw characters of your file — before it even starts making sense of bars and notes. If your quote is unclosed or an escape sequence is malformed, you land here.

AT001 — Unexpected character at comment start, expected '//' or '/*' but found '/value'

Severity: Error (Lexer)

Parser message: Unexpected character at comment start, expected '//' or '/*' but found '/%s'.

AT002 — Missing identifier after meta data start

Severity: Error (Lexer)

Parser message: Missing identifier after meta data start.

AT003 — Unexpected end of file

Severity: Error (Lexer)

Parser message: Unexpected end of file. Need 4 hex characters on a \uXXXX escape sequence.

AT004 — Invalid unicode value

Severity: Error (Lexer)

Parser message: Invalid unicode value. Need 4 hex characters on a \uXXXX escape sequence.

AT005 — Unsupported escape sequence

Severity: Error (Lexer)

Parser message: Unsupported escape sequence. Expected '\n', '\r', '\t', or '\uXXXX' but found '%s'.

AT006 — Unexpected end of file

Severity: Error (Lexer)

Parser message: Unexpected end of file. String not closed.

Structural errors

The characters read fine, but the shape of your file does not. Missing values, unclosed groups, notes that do not fit the staff kind, arguments that do not match any known signature — all show up here.

AT200 — Missing beat multiplier value after '*'

Severity: Error (Parser)

Parser message: Missing beat multiplier value after '*'.

AT201 — Missing duration value after ':'

Severity: Error (Parser)

Parser message: Missing duration value after ':'.

AT202 — Unexpected 'value' token

Severity: Error (Parser)

Parser message: Unexpected '%s' token. Expected one of following: %s

AT203 — Unexpected end of file

Severity: Error (Parser)

Parser message: Unexpected end of file.

AT204 — Unrecognized metadata 'value'

Severity: Error (Parser)

Parser message: Unrecognized metadata '%s'.

AT205 — Unrecognized property 'value'

Severity: Error (Parser)

Parser message: Unrecognized property '%s'.

AT206 — Unexpected end of file

Severity: Error (Parser)

Parser message: Unexpected end of file. Group not closed.

AT207 — Missing string for fretted note

Severity: Error (Parser)

Parser message: Missing string for fretted note.

AT208 — Note string is out of range

Severity: Error (Parser)

Parser message: Note string is out of range. Available range: 1-%s

AT209 — Unexpected value arguments 'value', Signature: value

Severity: Error (Parser)

Parser message: Unexpected %s arguments '%s', Signature: %s

AT210 — Missing arguments

Severity: Error (Parser)

Parser message: Missing arguments. Expected following arguments: %s

AT211 — Value is out of valid range

Severity: Error (Parser)

Parser message: Value is out of valid range. Allowed range: %s, Actual Value: %s

AT212 — Unrecogized property 'value', expected one of value

Severity: Error (Parser)

Parser message: Unrecogized property '%s', expected one of %s

AT213 — Invalid format for color

Severity: Error (Parser)

Parser message: Invalid format for color

AT214 — The 'value' effect needs value arguments per item

Severity: Error (Parser)

Parser message: The '%s' effect needs %s arguments per item. With %s points, %s arguments are needed, only %s arguments found.

AT215 — Cannot use pitched note value 'value' on value staff, please specify notes using the...

Severity: Error (Parser)

Parser message: Cannot use pitched note value '%s' on %s staff, please specify notes using the 'fret.string' syntax.

AT216 — Cannot use pitched note value 'value' on percussion staff, please specify percussion...

Severity: Error (Parser)

Parser message: Cannot use pitched note value '%s' on percussion staff, please specify percussion articulations with numbers or names.

AT217 — Unrecognized note value 'value'

Severity: Error (Parser)

Parser message: Unrecognized note value '%s'.

AT218 — Wrong note kind 'value' for staff with note kind 'value'

Severity: Error (Parser)

Parser message: Wrong note kind '%s' for staff with note kind '%s'. Do not mix incompatible staves and notes.

AT219 — Error parsing arguments: no overload matched arguments value

Severity: Error (Parser)

Parser message: Error parsing arguments: no overload matched arguments %s. Signatures: %s

AT220 — Error parsing arguments: unexpected additional arguments

Severity: Error (Parser)

Parser message: Error parsing arguments: unexpected additional arguments. Signatures: %s

AT221 — A string number can only be specified on pitched notes, use the 'fret.string' syntax to...

Severity: Error (Parser)

Parser message: A string number can only be specified on pitched notes, use the 'fret.string' syntax to specify the string of fretted notes. @since 1.9.0

Legacy syntax hints

Your file parses, but you are using a form that pre-dates alphaTex 1.7 or leaves redundant separators in place. alphaTab still accepts these; upgrading brings your notation in line with the current shape and unlocks better editor tooling.

AT300 — Expected no arguments, but found some

Severity: Warning

Parser message: Expected no arguments, but found some.

AT301 — Metadata arguments should be wrapped into parenthesis

Severity: Warning

Parser message: Metadata arguments should be wrapped into parenthesis.

AT302 — Metadata arguments should be placed before metadata properties

Severity: Warning

Parser message: Metadata arguments should be placed before metadata properties.

AT303 — Property arguments should be wrapped into parenthesis

Severity: Warning

Parser message: Property arguments should be wrapped into parenthesis.

AT304 — The beat multiplier should be specified after the beat effects

Severity: Warning

Parser message: The beat multiplier should be specified after the beat effects.

AT305 — This value should be rather specified via the properties

Severity: Warning

Parser message: This value should be rather specified via the properties.

AT306 — This staff metadata tag should be specified as staff property

Severity: Warning

Parser message: This staff metadata tag should be specified as staff property.

AT307 — The staff display property is not supported by the staff type, the value has no effect

Severity: Warning

Parser message: The staff display property is not supported by the staff type, the value has no effect. @since 1.9.0

AT400 — The dots separating score metadata, score contents and the sync points can be removed

Severity: Hint

Parser message: The dots separating score metadata, score contents and the sync points can be removed.