> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

<span id="faq" />

This page answers common questions about ArcPass.

<h2 id="installation-issues">
  Installation Issues
</h2>

<h3 id="plugin-not-loading">
  Plugin Not Loading
</h3>

**Symptom**: No ArcPass logs on server startup

**Solutions**:

1. Confirm JAR file is in `plugins` folder
2. Check Java version is 17+
3. Check server log for errors
4. Confirm using Paper/Spigot 1.18+ or Folia 1.19+

<h3 id="config-files-not-generated">
  Config Files Not Generated
</h3>

**Symptom**: `plugins/ArcPass` folder is empty or missing

**Solutions**:

1. Check folder write permissions
2. Check console for permission errors
3. Manually create `plugins/ArcPass` folder and restart

<h3 id="plugin-conflicts">
  Plugin Conflicts
</h3>

**Symptom**: Other plugins error after installing ArcPass

**Solutions**:

1. Check for duplicate dependency libraries
2. Try updating conflicting plugins
3. Check error logs for specifics
4. Report to Discord community

<h2 id="license-issues">
  License Issues
</h2>

<h3 id="validation-failed">
  Validation Failed
</h3>

**Symptom**: Console shows `License validation failed`

**Causes and Solutions**:

1. **Invalid key**
   * Check key in `license.yml` is correct
   * Mind case sensitivity

2. **Network issues**
   * Confirm server can reach `license.kitemc.com`
   * Check firewall settings

3. **Binding limit reached**
   * Login to dashboard and unbind unused servers
   * Or upgrade license plan

4. **License expired**
   * Check license validity
   * Renew or purchase new license

<h3 id="can-t-use-after-server-migration">
  Can't Use After Server Migration
</h3>

**Symptom**: License invalid after moving servers

**Solution**:

1. Login to [KiteMC License Center](https://license.kitemc.com/login)
2. Find your license
3. Unbind original server
4. Reactivate on new server

<h3 id="binding-failed">
  Binding Failed
</h3>

**Symptom**: `LIMIT_EXCEEDED` or `BINDING_FAILED`

**Solutions**:

1. Check current binding count
2. Unbind unused servers
3. Verify server IP and port

<h2 id="feature-issues">
  Feature Issues
</h2>

<h3 id="experience-not-increasing">
  Experience Not Increasing
</h3>

**Causes**:

1. No active season
2. Quest config error
3. Player lacks permission

**Solutions**:

1. Use `/arcpass admin season start` to start season
2. Check quest config files for syntax errors
3. Confirm player has `arcpass.use` permission

<h3 id="can-t-claim-rewards">
  Can't Claim Rewards
</h3>

**Causes**:

1. Level too low
2. Missing required tier
3. Already claimed

**Check**:

```
/arcpass admin lookup <player>
```

<h3 id="gui-won-t-open">
  GUI Won't Open
</h3>

**Causes**:

1. Plugin not fully initialized
2. License not activated
3. GUI config error

**Solutions**:

1. Wait for plugin to fully load
2. Check license status
3. Check `gui/*.yml` files for syntax errors

<h3 id="quest-progress-not-updating">
  Quest Progress Not Updating
</h3>

**Causes**:

1. Quest type configured incorrectly
2. Target parameters don't match
3. Quest conditions not met

**Troubleshoot**:

1. Verify quest type spelling
2. Check target parameters (block/entity names)
3. Enable debug mode:

   ```
   /arcpass admin debug toggle
   ```

<h2 id="compatibility-issues">
  Compatibility Issues
</h2>

<h3 id="folia-server-issues">
  Folia Server Issues
</h3>

**Q: Does ArcPass support Folia?**

A: Yes, fully supported. ArcPass auto-detects Folia and uses compatible schedulers.

**Q: Some features don't work on Folia?**

A: Check if third-party plugins support Folia:

* DeluxeTags doesn't support Folia - use TAB instead
* Some economy plugins may be incompatible

<h3 id="placeholderapi-variables-not-showing">
  PlaceholderAPI Variables Not Showing
</h3>

**Causes**:

1. PlaceholderAPI not installed
2. Expansion not registered
3. Variable name typo

**Solutions**:

1. Install PlaceholderAPI 2.11.0+
2. Restart server
3. Test with `/papi parse me %arcpass_level%`
4. Check variable names (case-sensitive)

<h3 id="economy-plugin-not-working">
  Economy Plugin Not Working
</h3>

**Symptom**: Tier purchase or economy rewards fail

**Solutions**:

1. Confirm Vault or CMI is installed
2. Confirm economy plugin (e.g., EssentialsX) works
3. Test: `/eco give <player> 100`

<h3 id="mythicmobs-jobs-quest-not-triggering">
  MythicMobs/Jobs Quest Not Triggering
</h3>

**Causes**:

1. Incompatible plugin version
2. Wrong ID configuration
3. Event not firing properly

**Solutions**:

1. Update to recommended versions
2. Check IDs (case-sensitive)
3. Enable debug mode to confirm events

<h2 id="performance-issues">
  Performance Issues
</h2>

<h3 id="server-lag">
  Server Lag
</h3>

**Causes**:

1. Slow database operations
2. Frequent leaderboard calculations
3. Too many online players

**Optimizations**:

1. Use MySQL instead of SQLite
2. Increase cache times
3. Optimize connection pool

```yaml theme={null}
# database.yml
mysql:
  pool:
    maximum-pool-size: 10
    minimum-idle: 5
```

<h3 id="high-memory-usage">
  High Memory Usage
</h3>

**Solutions**:

1. Check player data cache settings
2. Reduce unnecessary quest types
3. Periodically clean old data

<h2 id="configuration-issues">
  Configuration Issues
</h2>

<h3 id="yaml-syntax-errors">
  YAML Syntax Errors
</h3>

**Symptom**: Config files fail to load

**Common Errors**:

1. Using tabs instead of spaces for indent
2. Unescaped special characters
3. Missing space after colons

**Suggestions**:

* Use a YAML-aware editor (VSCode + YAML plugin)
* Use online YAML validators

<h3 id="garbled-chinese-unicode">
  Garbled Chinese/Unicode
</h3>

**Solutions**:

1. Ensure config files are saved as UTF-8
2. Convert encoding in Notepad++ or VSCode
3. Regenerate config files

<h2 id="getting-help">
  Getting Help
</h2>

If these solutions don't work:

1. **View detailed logs**

   ```
   /arcpass admin debug toggle
   ```

2. **Export diagnostics**

   ```
   /arcpass admin debug
   ```

3. **Contact support**

<Columns cols={2}>
  <Card title="Discord Community" icon="messages-square" href="https://discord.gg/dcsBw5Z5ZT">
    Get real-time help from our community
  </Card>

  <Card title="Email Support" icon="mail" href="mailto:starry_cbz@outlook.com">
    [starry\_cbz@outlook.com](mailto:starry_cbz@outlook.com)
  </Card>

  <Card title="License Center" icon="ticket" href="https://license.kitemc.com/dashboard/licenses">
    View license status and tickets
  </Card>

  <Card title="GitHub Issues" icon="bug" href="https://github.com/KiteMC/ArcPass/issues">
    Submit bug reports
  </Card>
</Columns>

When submitting issues, please provide:

* Server type and version
* ArcPass version
* Error log screenshots
* Relevant config files


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.