Common Issues

Installation Issues

App Won’t Open on macOS

If you see “GoNhanh.app is damaged and can’t be opened” after downloading manually, this is a security feature, not actual damage.

Solution:

Remove quarantine attribute

Open Terminal and run:

xattr -cr /Applications/GoNhanh.app

Launch the app

Double-click GoNhanh.app in Applications folder

Grant Accessibility permission

Go to System Settings → Privacy & Security → AccessibilityEnable GoNhanh in the list

Why does this happen?macOS quarantines apps downloaded from the internet. The xattr command removes this quarantine flag safely.

Accessibility Permission Issues

Gõ Nhanh can't capture keystrokes

The app requires Accessibility permission to intercept keyboard events system-wide.Check permission status:

Open System Settings
Go to Privacy & Security → Accessibility
Verify GoNhanh is in the list and enabled

Reset permission if not working:

tccutil reset Accessibility org.gonhanh

Then restart GoNhanh and grant permission again when prompted.

Permission granted but still not working

After granting permission, you must restart the app:

Right-click menu bar icon → Quit
Reopen from Applications folder
Test typing in any app

Permission revoked after macOS update

macOS updates sometimes reset Accessibility permissions.Solution:

Go to System Settings → Privacy & Security → Accessibility
Toggle GoNhanh off then on
Restart the app

Typing Issues

Character Swallowing in IDEs

Claude Code, VS Code, Cursor, Windsurf, and JetBrains IDEs may “swallow” the first character when the AI assistant autocomplete is active.

Example: Type được → only see ược (missing đ) Solution:

Open Settings

Click menu bar icon → Settings → Advanced tab

Add per-app config

Under “Per-app customization”, click +Select your IDE from the list

Increase delay

Drag the Delay slider to “Very High” (purple)This adds extra delay between backspaces and character insertion

Test

Settings auto-save. Return to your IDE and test typing

Why this works:IDEs with AI autocomplete have slower response times. The delay ensures the backspace is processed before inserting the new character.Each machine and IDE combination may need different delay levels. Experiment to find what works best.

Dính Chữ (Stuck Characters) in Address Bar

Problem: Typing Vietnamese in Chrome/Safari/Arc address bar causes stuck characters Example: Type dantri → see dân trí but URL doesn’t update correctly

How Gõ Nhanh handles this

Gõ Nhanh automatically detects address bars (AXComboBox elements) and uses selection-based replacement instead of backspace.This should work automatically. If you still see issues:

Check you’re running the latest version
Report the specific browser and version on GitHub

Input Source Not Switching

When using non-Latin input sources (Japanese, Chinese, Korean, etc.), Gõ Nhanh automatically disables itself.

Supported behavior:

Switch to Japanese → Menu bar shows あ, Gõ Nhanh disabled
Switch back to English → Menu bar shows V, Gõ Nhanh re-enabled
Switch to Vietnamese IME → Menu bar shows E, Gõ Nhanh disabled

Blocked languages:

// East Asian
ja, zh, zh-Hans, zh-Hant, ko

// Southeast Asian (non-Latin)
th, km, lo, my

// South Asian  
hi, bn, ta, and others

// Middle Eastern
ar, he, fa, ur

// Cyrillic
ru, uk, be, bg

Why?These input methods use different character systems incompatible with Vietnamese. Gõ Nhanh only works with Latin-based keyboards.

Auto-restore Not Working for English Words

Problem: Typing text → get têt instead of auto-restoring to text

Check you pressed Space

Auto-restore only triggers when you press Space after the word.Typing text alone won’t restore. Type text (with space) to trigger.

Some words can't be auto-restored

Words that form valid Vietnamese syllables cannot be auto-detected:

English	Becomes	Why
`mix`	`mĩ`	M + ĩ is valid Vietnamese
`box`	`bõ`	B + õ is valid Vietnamese
`six`	`sĩ`	S + ĩ is valid Vietnamese

Workaround: Press ESC after typing to restore, or temporarily disable Gõ Nhanh with Ctrl+Space.

Performance Issues

High CPU Usage

Check debug logging is disabled

Debug mode significantly impacts performance.Check if enabled:

ls -la /tmp/gonhanh_debug.log

Disable debug mode:

rm /tmp/gonhanh_debug.log

Then restart GoNhanh.

Normal CPU usage

Expected performance:

Idle: 0% CPU, ~5MB RAM
Typing: Brief spikes to 1-3% CPU
Latency: < 1ms per keystroke

If you see sustained high CPU usage, please report on GitHub with:

macOS version
GoNhanh version
List of running apps

Typing Lag or Delay

If you notice delay between pressing keys and seeing output, this is usually not GoNhanh.

Check these first:

Disable other input methods
- Go to System Settings → Keyboard → Input Sources
- Remove any other Vietnamese IMEs
- Keep only: English + GoNhanh
Check Accessibility conflicts
- Other apps with Accessibility permission can interfere
- Try temporarily disabling other accessibility tools
Test in different apps
- If lag only in specific app (e.g., Electron apps), increase per-app delay
- If lag everywhere, check Activity Monitor for other processes

Settings Issues

Settings Not Saving

Check preferences file exists:

ls -la ~/Library/Preferences/org.gonhanh.*

If file is corrupted, reset:

defaults delete org.gonhanh

Then restart GoNhanh. All settings will reset to defaults.

Shortcuts Not Working

Gõ tắt (abbreviations) not expanding

Check shortcut is saved:

Open Settings → Shortcuts
Verify your abbreviation is in the list
Format: from → to (e.g., vn → Việt Nam)

Trigger requirements:

Type the abbreviation exactly
Press Space or punctuation
The replacement happens immediately

Ctrl+Space not toggling Vietnamese

This is the global hotkey to enable/disable Gõ Nhanh.If not working:

Check another app isn’t capturing Ctrl+Space
Try clicking menu bar icon to toggle manually
Check keyboard is properly connected (Bluetooth keyboards sometimes drop modifiers)

App-Specific Issues

Electron Apps (Slack, Discord, Notion)

Problem: Occasional character loss or duplication Solution:

Update to latest version of the Electron app
Try increasing per-app delay in GoNhanh Settings → Advanced
Report persistent issues on GitHub

JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

Problem: Autocomplete popup interferes with typing Solution: GoNhanh automatically detects JetBrains apps (bundle ID: com.jetbrains.*) and uses selection-based replacement. If still having issues, increase delay in per-app settings.

Microsoft Excel

Problem: Cell autocomplete causes character issues Solution: GoNhanh automatically detects Excel and adjusts behavior. Update to latest version if problems persist.

Terminal (Terminal.app, iTerm2)

Best practice: Disable Gõ Nhanh when working in Terminal.Press Ctrl+Space to toggle off before typing commands.

Why: Shell commands are English-only. Vietnamese input interferes with:

Command names
File paths
Keyboard shortcuts (Ctrl+C, Ctrl+D, etc.)

Alternative: Add Terminal to exclusion list:

Settings → Advanced → Per-app customization
Add Terminal.app
Set to “Always disable”

Update Issues

Auto-update Check Fails

Gõ Nhanh checks for updates every 24 hours. If update check fails:

Check internet connection
Manually check: Menu bar → Settings → Updates
Or install manually from GitHub releases

Update Downloaded but Won’t Install

For Homebrew installations:

brew upgrade --cask gonhanh

For manual installations:

Download latest GoNhanh.dmg from GitHub
Quit current GoNhanh (menu bar → Quit)
Open DMG and drag to Applications (replace existing)
Run xattr -cr /Applications/GoNhanh.app
Relaunch

Debug Mode

Enable debug logging to diagnose issues.

Enable:

touch /tmp/gonhanh_debug.log

View logs:

tail -f /tmp/gonhanh_debug.log

Log format:

[HH:MM:SS.mmm] K:42 → Action:Send, BS:1, Out:[á]
[HH:MM:SS.mmm] M: setMethod(Telex)
[HH:MM:SS.mmm] P: RAM=5.2MB keys=1234

Disable:

rm /tmp/gonhanh_debug.log

Debug mode impacts performance. Only enable when troubleshooting.

Getting Help

If these solutions don’t help:

Check GitHub Issues: github.com/khaphanspace/gonhanh.org/issues
Report a bug: Include macOS version, GoNhanh version, and steps to reproduce
Community support: Join discussions on GitHub

Include in bug reports:

macOS version (sw_vers)
GoNhanh version (menu bar → About)
App where issue occurs (bundle ID helpful)
Debug log excerpt if available

Get Started

Installation

Features

Configuration

Troubleshooting

Installation Issues

App Won’t Open on macOS

Accessibility Permission Issues

Typing Issues

Character Swallowing in IDEs

Dính Chữ (Stuck Characters) in Address Bar

Input Source Not Switching

Auto-restore Not Working for English Words

Performance Issues

High CPU Usage

Typing Lag or Delay

Settings Issues

Settings Not Saving

Shortcuts Not Working

App-Specific Issues

Electron Apps (Slack, Discord, Notion)

JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

Microsoft Excel

Terminal (Terminal.app, iTerm2)

Update Issues

Auto-update Check Fails

Update Downloaded but Won’t Install

Debug Mode

Getting Help

Build docs developers (and LLMs) love

Get Started

Installation

Features

Configuration

Troubleshooting

Documentation Index

​Installation Issues

​App Won’t Open on macOS

​Accessibility Permission Issues

​Typing Issues

​Character Swallowing in IDEs

​Dính Chữ (Stuck Characters) in Address Bar

​Input Source Not Switching

​Auto-restore Not Working for English Words

​Performance Issues

​High CPU Usage

​Typing Lag or Delay

​Settings Issues

​Settings Not Saving

​Shortcuts Not Working

​App-Specific Issues

​Electron Apps (Slack, Discord, Notion)

​JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

​Microsoft Excel

​Terminal (Terminal.app, iTerm2)

​Update Issues

​Auto-update Check Fails

​Update Downloaded but Won’t Install

​Debug Mode

​Getting Help

Build docs developers (and LLMs) love

Installation Issues

App Won’t Open on macOS

Accessibility Permission Issues

Typing Issues

Character Swallowing in IDEs

Dính Chữ (Stuck Characters) in Address Bar

Input Source Not Switching

Auto-restore Not Working for English Words

Performance Issues

High CPU Usage

Typing Lag or Delay

Settings Issues

Settings Not Saving

Shortcuts Not Working

App-Specific Issues

Electron Apps (Slack, Discord, Notion)

JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

Microsoft Excel

Terminal (Terminal.app, iTerm2)

Update Issues

Auto-update Check Fails

Update Downloaded but Won’t Install

Debug Mode

Getting Help