{"record":{"id":"a1a01074dbba5220","repo":"phaserjs/phaser","slug":"wordwrapwidth-a-single-character","errorCode":null,"errorMessage":"wordWrapWidth < a single character","messagePattern":"wordWrapWidth < a single character","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/gameobjects/text/Text.js","lineNumber":491,"sourceCode":"                        var newWord = wordWithSpace;\n\n                        while (newWord.length)\n                        {\n                            newWord = newWord.slice(0, -1);\n                            var newLetterSpacingWidth = newWord.length * this.letterSpacing;\n                            wordWidth = context.measureText(newWord).width + newLetterSpacingWidth;\n\n                            if (wordWidth <= currentLineWidth)\n                            {\n                                break;\n                            }\n                        }\n\n                        // If wordWrapWidth is too small for even a single letter, shame user\n                        // failure with a fatal error\n                        if (!newWord.length)\n                        {\n                            throw new Error('wordWrapWidth < a single character');\n                        }\n\n                        // Replace current word in array with remainder\n                        var secondPart = word.substr(newWord.length);\n\n                        words[j] = secondPart;\n\n                        // Append first piece to output\n                        out += newWord;\n                    }\n\n                    // If existing word length is 0, don't include it\n                    var offset = (words[j].length) ? j : j + 1;\n\n                    // Collapse rest of sentence and remove any trailing white space\n                    var remainder = words.slice(offset).join(' ').replace(/[ \\n]*$/gi, '');\n\n                    // Prepend remainder to next line","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/gameobjects/text/Text.js#L473-L509","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase `wordWrapWidth` to be safely larger than the widest single character at the current font size.","Clamp the computed wrap width to a sensible floor (e.g. `Math.max(width, fontSize * 2)`).","Reduce the font size or switch to a narrower font for tight containers.","Avoid setting `wordWrap: { width: 0 }` from layout code by guarding against zero/negative dimensions."],"exampleFix":"// before\nthis.add.text(0, 0, 'Hello', { fontFamily: 'Arial', fontSize: '64px', wordWrap: { width: 20 } })\n// after\nthis.add.text(0, 0, 'Hello', { fontFamily: 'Arial', fontSize: '64px', wordWrap: { width: 200 } })","handlingStrategy":"validation","validationCode":"const fontSize = 32\nconst wrapWidth = Math.max(computedWidth, fontSize * 2)\nthis.add.text(0, 0, str, { fontSize: fontSize + 'px', wordWrap: { width: wrapWidth } })","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp computed wrap widths to a minimum greater than the widest glyph at the chosen font size.","Avoid setting wordWrap.width from layout code that can return 0/negative.","Test Text objects with the longest single character (e.g. 'W') at the chosen font size."],"tags":["text","wordwrap","style","runtime"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}