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

> Troubleshoot Rime deployment errors with this Wanxiang guide. Fix missing files, schema dependencies, and switch configs by checking your wanxiang and custom directories.

- Repository: [amzxyz/rime_wanxiang](https://github.com/amzxyz/rime_wanxiang)
- Tags: how-to-guide
- Published: 2026-02-24

---

**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`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/wanxiang.schema.yaml). At lines 13-16, the schema declares three mandatory dependencies that must be present for successful deployment:

```yaml
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`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/lua/super_processor.lua), which handle super tips, manual sorting, and input statistics, plus data files like [`wanxiang/lua/data/emoji.txt`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_reverse.schema.yaml), [`wanxiang_mixedcode.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_mixedcode.schema.yaml), or [`wanxiang_english.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/lua/data/emoji.txt) is deleted or the `lua_translator` entries are commented out in [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/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:
   ```bash
   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:
   ```bash
   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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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

```bash

# 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:

```yaml

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

dependencies:
  - wanxiang_mixedcode
  - wanxiang_reverse
  - wanxiang_english

```

Then verify the files exist:

```bash
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:

```text
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:

```bash
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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.dict.yaml) exists and that the `translator` block in [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`](https://github.com/amzxyz/rime_wanxiang/blob/main/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`.