charmbracelet/vhs · error · parser.Error

Expected alt character, got ${literal}

Error message

Expected alt character, got ${literal}

What it means

Alt in vhs takes exactly one argument: a single character (or valid key) to press with Alt held, e.g. 'Alt+b'. parseAlt walks the following tokens; if none yields an acceptable argument it records this error naming the token it stopped at and returns an ALT command with no Args.

Source

Thrown at parser/parser.go:372

// parseAlt parses an alt command.
// An alt command takes a character to type while the modifier is held down.
//
//	Alt+<character>
func (p *Parser) parseAlt() Command {
	if p.peek.Type == token.PLUS {
		p.nextToken()
		if p.peek.Type == token.STRING ||
			p.peek.Type == token.ENTER ||
			p.peek.Type == token.LEFT_BRACKET ||
			p.peek.Type == token.RIGHT_BRACKET ||
			p.peek.Type == token.TAB {
			c := p.peek.Literal
			p.nextToken()
			return Command{Type: token.ALT, Args: c}
		}
	}

	p.errors = append(p.errors, NewError(p.cur, "Expected alt character, got "+p.cur.Literal))
	return Command{Type: token.ALT}
}

// parseShift parses a shift command.
// A shift command takes one character and types while shift is held down.
//
//	Shift+<char>
//	E.g.
//	Shift+A
//	Shift+Tab
//	Shift+Enter
func (p *Parser) parseShift() Command {
	if p.peek.Type == token.PLUS {
		p.nextToken()
		if p.peek.Type == token.STRING ||
			p.peek.Type == token.ENTER ||
			p.peek.Type == token.LEFT_BRACKET ||
			p.peek.Type == token.RIGHT_BRACKET ||

View on GitHub (pinned to c073383b5d)

Solutions

1. Give Alt exactly one character: 'Alt+b', 'Alt+x'.
2. For key-combos with modifiers use the Ctrl chain syntax (e.g. 'Ctrl+Alt+...') only with supported keys.
3. Remove the Alt line if it was accidental.

Example fix

// before (.tape)
Alt+foo
// after (.tape)
Alt+f

func validAltArg(a string) bool { return len(a) == 1 }

When it happens

Trigger: 'Alt' with no argument ('Alt' alone or 'Alt+' at end of line), or an argument that is not a single character / valid key token.

Common situations: Writing multi-character sequences after Alt ('Alt+foo'); leaving a dangling 'Alt+' after deleting the key; confusing Alt with Ctrl chains.

Related errors

• Expected time after ${literal}
• Expected control character with args, got ${literal}
• Invalid command: ${literal}
• Wait+ expects Line or Screen
• Wait expects positive duration

AI-assisted analysis of charmbracelet/vhs@c073383b5d (2026-09-02). Data as JSON: /api/errors/818411d4dde3f0ce. Report an issue: GitHub.