Troubleshooting

Troubleshooting

Always check the server console first. AFK Area reports configuration errors, missing integrations, invalid regions and persistence failures there.

AFK Area does not start

Check:

1. You are running Paper.
2. VertexCore 1.1.0 or newer is installed and enabled.
3. Your Java version is supported by your Paper build.
4. config.yml is valid.
5. The console does not report database initialization failures.

/afkarea says the area is unavailable

Check the configured target:

afk:
  auto-teleport:
    target-area: spawn-afk

Then verify:

• Area exists
• Area is enabled
• Teleport destination is set
• Destination world is loaded

Inspect:

/afkarea info spawn-afk

Automatic teleporting does not happen

Check:

• afk.auto-teleport.enabled: true
• Correct target ID
• Valid teleport destination
• teleport-after-seconds >= mark-after-seconds
• Player does not have afkarea.bypass.auto-afk
• Player is not spectator, dead or sleeping

Use:

/afkarea status <player>

Player never becomes AFK

Check whether the player continuously generates tracked activity.

Also check:

afkarea.bypass.auto-afk

WorldGuard area does not work

Check:

1. WorldEdit is installed.
2. WorldGuard is installed and enabled.
3. The region exists.
4. The stored world exists.
5. The region ID is correct.

Inspect:

/afkarea info <id>

See WorldGuard Integration.

Rewards do not run

Check:

• Player is inside the expected area
• Reward configuration exists
• Reward is enabled
• Reward has at least one command
• Weight is greater than 0
• Player meets reward permission requirements
• Player does not have afkarea.bypass.rewards
• IP reward limit allows the player
• Schedule is valid

Useful commands:

/afkarea reward info <area>
/afkarea reward list <area>
/afkarea status <player>

Only some players on the same connection receive rewards

This may be the IP limit:

anti-abuse:
  max-rewarding-players-per-ip: 2

Use:

/afkarea status <player>

For legitimate shared connections, see Anti-Abuse & Households.

PlaceholderAPI placeholders do not work

Check:

• PlaceholderAPI is installed and enabled
• Console reports PlaceholderAPI integration as available
• You use the afkarea identifier
• Receiving plugin supports PlaceholderAPI

Test:

%afkarea_state%

Restart after adding PlaceholderAPI to an already running server.

TAB suffix does not appear

When TAB is installed, AFK Area intentionally disables its native tab marker.

Check:

• PlaceholderAPI is installed
• TAB is enabled
• %afkarea_tab_suffix% is used in TAB

If TAB is present without PlaceholderAPI, AFK Area logs a warning.

Bossbar or actionbar is missing

Check:

display:
  bossbar:
    enabled: true
  actionbar:
    enabled: true

Or enable them with:

/afkarea display bossbar on
/afkarea display actionbar on

The player must have an active AFK area session.

/afkarea reload fails

Look for Configuration error messages in the console.

Common causes:

• Invalid AFK timings
• Invalid IP limit
• Unsupported database backend
• Blank MySQL URL/user
• Invalid table prefix
• Invalid bossbar color/style

When validation fails, the previous active configuration remains in use.

Database changes do not apply after reload

This is expected. Database settings require a server restart.

Data appears missing after changing backend

Each backend has separate storage.

Switching from JSON to H2/MySQL does not automatically migrate old records.

See Database & Storage.

Useful diagnostics

/afkarea list
/afkarea info <area>
/afkarea status [player]
/afkarea stats <player>
/afkarea reward info <area>
/afkarea reward list <area>
/afkarea household info <player>

Reporting a problem

Include:

• Paper version
• Java version
• AFK Area version
• VertexCore version
• Optional integration versions
• Relevant configuration
• Full error/stack trace
• Steps to reproduce

Issue tracker:

https://github.com/Tebrox-Development/AFKArea/issues