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]


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.


Error message unexpected \new

A \score block must contain a single music expression. If instead it contains several \new Staff, \new StaffGroup or similar contexts introduced with \new without them being enclosed in either curly brackets, { … }, or double angle brackets, << … >>, like this:

\score {
  % Invalid! Generates error: syntax error, unexpected \new
  \new Staff { … }
  \new Staff { … }
}

the error message will be produced.

To avoid the error, enclose all the \new statements in curly or double angle brackets.

Using curly brackets will introduce the \new statements sequentially:

\score {
  {
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  }
}

[image of music]

but more likely you should be using double angle brackets so the new staves are introduced in parallel, i.e. simultaneously:

\score {
  <<
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  >>
}

[image of music]


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

LilyPond — Usage v2.19.4 (development-branch).