[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Error messages ][ Up : Running lilypond ][]

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  
An extra staff appears  
Error message Unbound variable %  
Error message FT_Get_Glyph_Name  
Warning staff affinities should only decrease  
Error message unexpected \new  
Warning this voice needs a \voiceXx or \shiftXx setting  
[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Common errors ][ Up : Common errors ][]

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.

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Music runs off the page ][ Up : Common errors ][]

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]

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < An extra staff appears ][ Up : Common errors ][]

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, (;).

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Error message Unbound variable % ][ Up : Common errors ][]

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.

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Error message FT_Get_Glyph_Name ][ Up : Common errors ][]

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.

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Warning staff affinities should only decrease ][ Up : Common errors ][]

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]

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Error message unexpected new ][ Up : Common errors ][]

Warning this voice needs a \voiceXx or \shiftXx setting

If notes from two different voices with stems in the same direction occur at the same musical moment, but the voices have no voice-specific shifts specified, the warning message ‘warning: this voice needs a \voiceXx or \shiftXx setting’ will appear when compiling the LilyPond file. This warning will appear even when the notes have no visible stems, e.g., whole notes, if the stems for shorter notes at the same pitch would be in the same direction.

Remember that the stem direction depends on the position of the note on the staff unless the stem direction is specified, for example by using \voiceOne, etc. In this case the warning will appear only when the stems happen to be in the same direction, i.e., when the notes are in the same half of the staff.

By placing the notes in voices with stem directions and shifts specified, for example by using \voiceOne, etc., these warnings may be avoided.

Notes in higher numbered voices, \voiceThree, etc., are automatically shifted to avoid clashing note columns. This causes a visible shift for notes with stems, but whole notes are not visibly shifted unless an actual clash of the note heads occurs, or when the voices cross over from their natural order (when \voiceThree is higher than \voiceOne, etc.).

See also

Explicitly instantiating voices, Real music example, Single-staff polyphony, Collision resolution.

[ << Running lilypond ][Top][Contents][Index][ Updating files with convert-ly >> ]
[ < Error message unexpected new ][ Up : Common errors ][]

<< Back to Documentation Index

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