{"record":{"id":"7ec0e22c707385e8","repo":"microsoft/playwright","slug":"unknown-key-keystring","errorCode":null,"errorMessage":"Unknown key: \"${keyString}\"","messagePattern":"Unknown key: \"(.+?)\"","errorType":"validation","errorClass":"NonRecoverableDOMError","httpStatus":null,"severity":"error","filePath":"packages/playwright-core/src/server/input.ts","lineNumber":74,"sourceCode":"  async apiDown(progress: Progress, key: string) {\n    await this._page.instrumentation.onBeforeInputAction(progress, this._page);\n    await this.down(progress, key);\n  }\n\n  async down(progress: Progress, key: string) {\n    const description = this._keyDescriptionForString(key);\n    const autoRepeat = this._pressedKeys.has(description.code);\n    this._pressedKeys.add(description.code);\n    if (kModifiers.includes(description.key as types.KeyboardModifier))\n      this._pressedModifiers.add(description.key as types.KeyboardModifier);\n    await this._raw.keydown(progress, this._pressedModifiers, key, description, autoRepeat);\n  }\n\n  private _keyDescriptionForString(str: string): KeyDescription {\n    const keyString = resolveSmartModifierString(str);\n    let description = usKeyboardLayout.get(keyString);\n    if (!description)\n      throw new NonRecoverableDOMError(`Unknown key: \"${keyString}\"`);\n    const shift = this._pressedModifiers.has('Shift');\n    description = shift && description.shifted ? description.shifted : description;\n\n    // if any modifiers besides shift are pressed, no text should be sent\n    if (this._pressedModifiers.size > 1 || (!this._pressedModifiers.has('Shift') && this._pressedModifiers.size === 1))\n      return { ...description, text: '' };\n    return description;\n  }\n\n  async apiUp(progress: Progress, key: string) {\n    await this._page.instrumentation.onBeforeInputAction(progress, this._page);\n    await this.up(progress, key);\n  }\n\n  async up(progress: Progress, key: string) {\n    const description = this._keyDescriptionForString(key);\n    if (kModifiers.includes(description.key as types.KeyboardModifier))\n      this._pressedModifiers.delete(description.key as types.KeyboardModifier);","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/server/input.ts#L56-L92","documentation":"Thrown by Keyboard._keyDescriptionForString() as a NonRecoverableDOMError when the resolved key string is not found in the US keyboard layout map. The method resolves smart modifiers (ControlOrMeta) first, then looks up the key in usKeyboardLayout. If no entry exists, the key is unknown to Playwright's keyboard emulation. NonRecoverableDOMError means the action will not be retried by the progress system.","triggerScenarios":"Calling page.keyboard.press(), keyboard.down(), keyboard.up(), or page.press() with a key name that is not in the US keyboard layout. Examples include typos like 'Retern', unsupported keys like 'Tab' (actually supported but easy to misspell), or keys from non-US layouts that have no US equivalent.","commonSituations":"Typo in key name (e.g., 'Controll' instead of 'Control'). Using a non-standard key name from documentation or memory. Attempting to press media keys or application keys not in the layout. Passing a multi-character string that is not a recognized key combination.","solutions":["Use a valid key name from the US keyboard layout: 'Enter', 'Tab', 'Escape', 'ArrowUp', 'Control', 'Shift', 'Alt', 'Meta', 'Backspace', 'Delete', 'Home', 'End', 'PageUp', 'PageDown', 'F1'-'F12', or single characters like 'a', '1', '@'.","Use 'ControlOrMeta' as a cross-platform modifier alias (resolves to Meta on macOS, Control elsewhere).","For typing text (not key presses), use page.keyboard.type() or page.fill() instead of individual key presses.","Check the Playwright key names documentation for the complete list of supported keys."],"exampleFix":"// before\nawait page.keyboard.press('Retern');\n\n// after\nawait page.keyboard.press('Enter');","handlingStrategy":"validation","validationCode":"const VALID_KEYS = new Set(['Enter','Tab','Escape','Backspace','Delete','Insert','Home','End','PageUp','PageDown','ArrowUp','ArrowDown','ArrowLeft','ArrowRight','Control','Shift','Alt','Meta','ControlOrMeta','F1','F2','F3','F4','F5','F6','F7','F8','F9','F10','F11','F12']);\nfunction validateKey(key) {\n  if (!VALID_KEYS.has(key) && key.length > 1)\n    throw new Error(`Unknown key: ${key}`);\n}","typeGuard":"function isValidKey(key: string): boolean {\n  const SPECIAL_KEYS = ['Enter','Tab','Escape','Backspace','Delete','Insert','Home','End','PageUp','PageDown','ArrowUp','ArrowDown','ArrowLeft','ArrowRight','Control','Shift','Alt','Meta','ControlOrMeta'];\n  return key.length === 1 || SPECIAL_KEYS.includes(key) || /^F([1-9]|1[0-2])$/.test(key);\n}","tryCatchPattern":null,"preventionTips":["Use key names from the Playwright keyboard layout documentation.","Use 'ControlOrMeta' for cross-platform modifier.","Use keyboard.type() for text input instead of individual key presses."],"tags":["keyboard","key","input","non-retriable","validation"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}