1.4 Common errors

The error conditions described below occur often, yet the cause is not obvious or easily found. Once seen and understood, they are easily handled.


Music runs off the page

Music running off the page over the right margin or appearing unduly compressed is almost always due to entering an incorrect duration on a note, causing the final note in a measure to extend over the bar line. It is not invalid if the final note in a measure does not end on the automatically entered bar line, as the note is simply assumed to carry over into the next measure. But if a long sequence of such carry-over measures occurs the music can appear compressed or may flow off the page because automatic line breaks can be inserted only at the end of complete measures, i.e., where all notes end before or at the end of the measure.

Note: An incorrect duration can cause line breaks to be inhibited, leading to a line of highly compressed music or music which flows off the page.

The incorrect duration can be found easily if bar checks are used, see Bar and bar number checks.

If you actually intend to have a series of such carry-over measures you will need to insert an invisible bar line where you want the line to break. For details, see Bar lines.


An extra staff appears

If contexts are not created explicitly with \new or \context, they will be silently created as soon as a command is encountered which cannot be applied to an existing context. In simple scores the automatic creation of contexts is useful, and most of the examples in the LilyPond manuals take advantage of this simplification. But occasionally the silent creation of contexts can give rise to unexpected new staves or scores. For example, it might be expected that the following code would cause all note heads within the following staff to be colored red, but in fact it results in two staves with the note heads remaining the default black in the lower staff.

\override Staff.NoteHead #'color = #red
\new Staff { a }

[image of music]

This is because a Staff context does not exist when the override is processed, so one is implicitly created and the override is applied to it, but then the \new Staff command creates another, separate, staff into which the notes are placed. The correct code to color all note heads red is

\new Staff {
  \override Staff.NoteHead #'color = #red
  a
}

[image of music]

As a second example, if a \relative command is placed inside a \repeat command, two staves result, the second offset from the first, because the \repeat command generates two \relative blocks, which each implicitly create Staff and Voice blocks.

\repeat unfold 2 {
  \relative c' { c4 d e f }
}

[image of music]

Explicitly instantiating the Voice context fixes the problem:

\new Voice {
  \repeat unfold 2 {
    \relative c' { c4 d e f }
  }
}

[image of music]


Apparent error in ../ly/init.ly

Various obscure error messages may appear about syntax errors in ‘../ly/init.ly’ if the input file is not correctly formed, for example, if it does not contain correctly matched braces or quote signs.

The most common error is a missing brace, (}), at the end of a score block. Here the solution is obvious: check the score block is correctly terminated. The correct structure of an input file is described in How LilyPond input files work. Using an editor which automatically highlights matching brackets and braces is helpful to avoid such errors.

A second common cause is no white space between the last syllable of a lyrics block and the terminating brace, (}). Without this separation the brace is taken to be part of the syllable. It is always advisable to ensure there is white space before and after every brace. For the importance of this when using lyrics, see Entering lyrics.

This error message can also appear if a terminating quote sign, ("), is omitted. In this case an accompanying error message should give a line number close to the line in error. The mismatched quote will usually be on the line one or two above.


Error message Unbound variable %

This error message will appear at the bottom of the console output or log file together with a “GUILE signalled an error …” message every time a Scheme routine is called which (invalidly) contains a LilyPond rather than a Scheme comment.

LilyPond comments begin with a percent sign, (%), and must not be used within Scheme routines. Scheme comments begin with a semi-colon, (;).


Error message FT_Get_Glyph_Name

This error messages appears in the console output or log file if an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see Text encoding.


Warning staff affinities should only decrease

This warning can appear if there are no staves in the printed output, for example if there are just a ChordName context and a Lyrics context as in a lead sheet. The warning messages can be avoided by making one of the contexts behave as a staff by inserting

\override VerticalAxisGroup #'staff-affinity = ##f

at its start. For details, see “Spacing of non-staff lines” in Flexible vertical spacing within systems.


Other languages: deutsch, español, français, magyar, italiano, 日本語.
About automatic language selection.

LilyPond — Usage