phaserjs/phaser · error · Error

wordWrapWidth < a single character

Error message

wordWrapWidth < a single character

What it means

Text.js:491 throws during word-wrap when the shrunken-word loop produces an empty `newWord`, meaning `wordWrapWidth` is smaller than the measured width of a single character. Phaser treats this as a fatal misconfiguration rather than producing garbled output, per the inline comment ('shame user failure with a fatal error').

Source

Thrown at src/gameobjects/text/Text.js:491

                        var newWord = wordWithSpace;

                        while (newWord.length)
                        {
                            newWord = newWord.slice(0, -1);
                            var newLetterSpacingWidth = newWord.length * this.letterSpacing;
                            wordWidth = context.measureText(newWord).width + newLetterSpacingWidth;

                            if (wordWidth <= currentLineWidth)
                            {
                                break;
                            }
                        }

                        // If wordWrapWidth is too small for even a single letter, shame user
                        // failure with a fatal error
                        if (!newWord.length)
                        {
                            throw new Error('wordWrapWidth < a single character');
                        }

                        // Replace current word in array with remainder
                        var secondPart = word.substr(newWord.length);

                        words[j] = secondPart;

                        // Append first piece to output
                        out += newWord;
                    }

                    // If existing word length is 0, don't include it
                    var offset = (words[j].length) ? j : j + 1;

                    // Collapse rest of sentence and remove any trailing white space
                    var remainder = words.slice(offset).join(' ').replace(/[ \n]*$/gi, '');

                    // Prepend remainder to next line

View on GitHub (pinned to 41be1e462b)

Solutions

1. Increase `wordWrapWidth` to be safely larger than the widest single character at the current font size.
2. Clamp the computed wrap width to a sensible floor (e.g. `Math.max(width, fontSize * 2)`).
3. Reduce the font size or switch to a narrower font for tight containers.
4. Avoid setting `wordWrap: { width: 0 }` from layout code by guarding against zero/negative dimensions.

Example fix

// before
this.add.text(0, 0, 'Hello', { fontFamily: 'Arial', fontSize: '64px', wordWrap: { width: 20 } })
// after
this.add.text(0, 0, 'Hello', { fontFamily: 'Arial', fontSize: '64px', wordWrap: { width: 200 } })

const fontSize = 32
const wrapWidth = Math.max(computedWidth, fontSize * 2)
this.add.text(0, 0, str, { fontSize: fontSize + 'px', wordWrap: { width: wrapWidth } })

When it happens

Trigger: Setting `style: { wordWrap: { width: N } }` (or `wordWrapWidth: N`) where N is less than the widest single glyph at the chosen font/size. Also triggering when very large font sizes or wide letters (e.g. 'W') are combined with a tiny wrap width.

Common situations: Responsive layouts that compute `wordWrapWidth` from viewport and clamp to 0 or a near-zero value; setting `wordWrapWidth` equal to or less than the font size; using a large `fontSize` with a narrow container.

Related errors

• Particle has no texture frame
• GetCentroid points be a non-empty array

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/a1a01074dbba5220. Report an issue: GitHub.