How to Troubleshoot Deployment Errors in Rime Input Method Schemas: Complete Wanxiang Guide

Most Rime deployment failures stem from missing custom patch files, absent schema dependencies, or misconfigured switches, which can be diagnosed via the Rime log and fixed by verifying file presence in the wanxiang/ and custom/ directories.

Deploying complex Rime schemas like Wanxiang from the amzxyz/rime_wanxiang repository requires precise file alignment across multiple components. When the input method aborts during initialization or produces no candidates, the root cause typically lies in the modular architecture of auxiliary schemas, Lua processors, and user-specific configuration overrides.

Understanding the Wanxiang Schema Architecture

The Wanxiang suite relies on a modular pipeline defined in wanxiang/wanxiang.schema.yaml. At lines 13-16, the schema declares three mandatory dependencies that must be present for successful deployment:

dependencies:
  - wanxiang_mixedcode    # 混合编码

  - wanxiang_reverse      # 部件拆字，反查及辅码

  - wanxiang_english      # 英文

If any of these auxiliary schemas are missing from the Rime user directory, the deployment engine logs a schema dependency not found error and terminates. The architecture extends beyond YAML definitions to include Lua-based processors located in wanxiang/lua/super_processor.lua, which handle super tips, manual sorting, and input statistics, plus data files like wanxiang/lua/data/emoji.txt that power real-time candidate enrichment.

Common Deployment Failure Scenarios

Missing Custom Patch Files

The most frequent cause of immediate deployment failure is the absence of user-specific overrides in the custom/ directory. Wanxiang requires files such as custom/wanxiang.custom.yaml to exist before the engine can merge default settings with user preferences. If these are deleted or never copied from the repository templates, Rime logs file not found or failed to load errors in the system log.

Broken Schema Dependencies

When wanxiang_reverse.schema.yaml, wanxiang_mixedcode.schema.yaml, or wanxiang_english.schema.yaml are corrupted or absent, the main schema aborts during the dependency resolution phase. Check the Rime log (%APPDATA%\Rime\Rime.log on Windows or ~/.local/share/rime/rime.log on Linux) for entries like:

[error] schema dependency not found: wanxiang_reverse

Disabled Dictionary via Switch States

If no candidates appear after typing, verify that ascii_mode has not been accidentally toggled to English input. The status bar displays active switches (中文/英文, 简体/繁体). A disabled main dictionary often results from switches set to states that bypass the primary translator, such as abbreviation-only modes or character set filters that exclude all candidates.

Missing Data Files for Lua Filters

Features like emoji conversion, Unicode input (U4E00 → 「一」), and numeric-to-Chinese conversion rely on specific data files and recognizer patterns (^U[a-f0-9]+ for Unicode, ^R[0-9]+ for numbers). If wanxiang/lua/data/emoji.txt is deleted or the lua_translator entries are commented out in wanxiang.schema.yaml, these functions return "未找到匹配项" or no output.

Step-by-Step Debugging Workflow

1. Locate and examine the Rime log file to identify the exact error message and affected component.

2. Verify the presence of all three dependency schemas in the user directory:

   ls wanxiang/wanxiang_reverse.schema.yaml
   ls wanxiang/wanxiang_mixedcode.schema.yaml
   ls wanxiang/wanxiang_english.schema.yaml

3. Confirm custom patch files exist in the custom/ subdirectory. If missing, copy them from the repository templates:

   cp wanxiang/custom/wanxiang.custom.yaml ~/.config/rime/wanxiang/custom/

4. Validate YAML syntax using an online linter. A single stray tab or missing colon in wanxiang.schema.yaml can abort the entire loading process.

5. Check switch states via the input method status bar to ensure ascii_mode is not active and super_tips is enabled if you require emoji or translation features.

6. Redeploy the schema using your platform's method:

   • Windows (Weasel): Right-click the Rime tray icon → "重新部署"
   • macOS (Squirrel): Preferences → "重新部署"
   • Linux (ibus-rime): ibus restart followed by rime_deployer

7. Regenerate missing custom files using fast-switch commands. Type /flypy or /pinyin and press Enter; the lua/set_schema.lua script automatically copies templates from custom/ to the root directory if files are missing.

Code Examples and Configuration Fixes

Manually Deploying and Verifying File Structure

# Copy the entire Wanxiang directory to the Rime user folder

cp -r /path/to/wanxiang ~/.config/ibus/rime/

# Verify all required files are present

ls -la ~/.config/ibus/rime/wanxiang/custom/*.custom.yaml
ls ~/.config/ibus/rime/wanxiang/lua/super_processor.lua
ls ~/.config/ibus/rime/wanxiang/lua/data/emoji.txt

Fixing Schema Dependencies

If the log indicates a missing dependency, ensure all three auxiliary schemas are intact:

# Lines 13-16 in wanxiang/wanxiang.schema.yaml

dependencies:
  - wanxiang_mixedcode
  - wanxiang_reverse
  - wanxiang_english

Then verify the files exist:

test -f wanxiang/wanxiang_reverse.schema.yaml || echo "MISSING: reverse schema"
test -f wanxiang/wanxiang_mixedcode.schema.yaml || echo "MISSING: mixedcode schema"
test -f wanxiang/wanxiang_english.schema.yaml || echo "MISSING: english schema"

Recovering from Switch Misconfiguration

If you accidentally disabled the main dictionary or enabled a restrictive filter, toggle the switches using the default key bindings defined in the schema's key_binder section:

Ctrl+A   # Toggle tone_hint (声调提示)

Ctrl+G   # Toggle charset_filter (字符集过滤)

Ctrl+T   # Toggle super_tips (emoji and translation hints)

Ctrl+Shift+1  # Toggle ascii_mode between Chinese and English input

Restoring Missing Emoji Data

If the super_tips filter shows no emoji candidates, recreate the data file:

mkdir -p wanxiang/lua/data
cat > wanxiang/lua/data/emoji.txt <<'EOF'
😀    grinning face
😂    face with tears of joy
👍    thumbs up
👎    thumbs down
EOF

# Redeploy to load the restored data

rime_deployer

Summary

• Deployment failures in Wanxiang almost always trace back to missing files in the custom/ directory or absent auxiliary schemas defined in the dependencies block.
• Check the Rime log (Rime.log or rime.log) for specific error messages regarding file loading or dependency resolution.
• Verify switch states when candidates fail to appear; ascii_mode or restrictive filters can disable the main dictionary without logging errors.
• Use fast-switch commands (/flypy, /pinyin) to auto-generate missing custom configuration files from repository templates.
• Maintain the Lua data files in wanxiang/lua/data/ to ensure emoji, abbreviation, and Unicode conversion features function correctly.

Frequently Asked Questions

Why does Rime show "部署失败" immediately after installing Wanxiang?

This error indicates the engine cannot load required configuration files. Check that custom/wanxiang.custom.yaml exists and that the three dependency schemas (wanxiang_reverse, wanxiang_mixedcode, wanxiang_english) are present in your Rime user directory. The log file will specify exactly which file is missing or which YAML syntax error is preventing parsing.

How do I fix the issue where no candidates appear after typing?

First, check the status bar to confirm you are not in ascii_mode (英文模式). If the status shows English input or a disabled dictionary switch, press Ctrl+Shift+1 or use the schema switcher to return to Chinese input. If switches are correct, verify that wanxiang.dict.yaml exists and that the translator block in wanxiang.schema.yaml is not commented out.

What should I do if fast-switch commands like /flypy or /pinyin return "未找到方案文件"?

This occurs when the custom patch files required for schema switching are missing. Type the command once to trigger the lua/set_schema.lua script, which will copy the appropriate template from custom/ to the root directory. If the error persists, manually copy wanxiang/custom/wanxiang.custom.yaml to your Rime user directory and redeploy.

Where can I find the Rime log files to debug schema errors?

On Windows, open %APPDATA%\Rime\Rime.log in a text editor. On macOS, check ~/Library/Logs/rime.log. On Linux (ibus-rime or fcitx5-rime), the log is typically located at ~/.local/share/rime/rime.log or printed to stderr when running rime_deployer from the terminal. Search for lines containing error, failed to load, or schema dependency not found.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}