Configuration
Configuration
Complete reference for all settings, environment variables, cache behavior, and detailed provider documentation with errors.
Admin Panel Settings
Open settings via the gear icon on the Plugin Browser page.
Settings Reference
| Setting |
Default |
Range |
Env Variable |
Description |
| Cache Duration |
30 min |
0–1440 min |
PLUGINS_CACHE_DURATION (seconds, default 1800) |
How long API responses are cached |
| Request Timeout |
10 sec |
1–30 sec |
PLUGINS_REQUEST_TIMEOUT |
Max wait time for API response |
| Plugins Per Page |
20 |
5–100 |
PLUGINS_PER_PAGE |
Results per browse page |
| Auto Replace |
On |
Toggle |
PLUGINS_AUTO_REPLACE_VERSIONS |
Remove old versions on update |
| CurseForge API Key |
— |
Text |
CURSEFORGE_API_KEY |
Required for CurseForge (password field) |
All Environment Variables
| Variable |
Default |
Description |
PLUGINS_CACHE_DURATION |
1800 |
Cache duration in seconds |
PLUGINS_REQUEST_TIMEOUT |
10 |
API timeout in seconds |
PLUGINS_PER_PAGE |
20 |
Plugins per browse page |
PLUGINS_AUTO_REPLACE_VERSIONS |
true |
Auto-remove old versions |
CURSEFORGE_API_KEY |
— |
CurseForge API key (shared with Game Mods + Modpacks) |
After changes: php artisan config:clear
Provider: SpigotMC / Spiget API (Detailed)
Overview
No configuration required. Largest Minecraft plugin ecosystem.
Technical Details
| Property |
Value |
| API Base |
https://api.spiget.org/v2 |
| Auth |
None required |
| Empty query sort |
-downloads at /resources |
| Search endpoint |
/search/resources/{query} |
| Total count |
X-Total response header |
| Icon URL |
https://www.spigotmc.org/{icon.url} |
Download Verification
SpigotMC uses a HEAD request to check if the download URL returns an actual JAR file:
| Content-Type |
Result |
application/java-archive or similar |
has_direct_download: true — installs directly |
text/html or other |
has_direct_download: false — manual download required |
This check is critical because premium/restricted resources return an HTML page instead of a JAR file.
SpigotMC-Specific Notes
- No dependency API available — dependencies must be installed manually
- Premium resources show a link to the SpigotMC page for manual download
- Icon URLs are relative — prefixed with
https://www.spigotmc.org/
- Some resources may have outdated Spiget data — refresh by visiting the SpigotMC page
SpigotMC-Specific Errors
| Error |
Cause |
Solution |
| Empty results |
Spiget API cache stale or down |
Try again later, use different search terms |
| Download returns HTML |
Premium/restricted resource |
Download manually from SpigotMC |
| No version filter |
Spiget doesn't provide reliable version filtering |
Browse results may include incompatible plugins |
| Icon doesn't load |
Relative URL issue |
Non-functional, plugin works correctly |
Provider: CurseForge / Bukkit Plugins (Detailed)
Overview
Requires free API key. Full-featured with recursive dependency resolution.
Technical Details
| Property |
Value |
| API Base |
https://api.curseforge.com/v1 |
| Auth |
x-api-key header |
| Class ID |
5 (Bukkit Plugins) — different from Mods (9137) and Modpacks (4471) |
| Game ID |
432 (Minecraft) |
| Default sort |
Popularity(2) if no query; Featured(1) with query |
| Sort 4 (Name) |
Sort order toggles to ascending (only ascending sort) |
| Max page size |
50, total cap 10,000 |
Dependency Resolution (Recursive)
relationType=3 = required dependency- Fully recursive: Dependencies of dependencies are also resolved
- Each dependency triggers a Filament notification
- Dependencies installed before the main plugin
Description Enrichment
For plugins with empty descriptions in search results:
getModDescription() fetches /mods/{modId}/description (HTML)- Cached and displayed in detail view
MC Version Extraction
- From
gameVersions array filtered by \d+\.\d+ regex
- Fallback to general version strings
CurseForge-Specific Errors
| Error |
Cause |
Solution |
| "CurseForge API key not set" |
No key configured |
Add key in settings or CURSEFORGE_API_KEY |
| HTTP 403 |
Invalid key |
Regenerate at console.curseforge.com |
| HTTP 429 |
Rate limit exceeded |
Increase cache duration, wait |
| Empty download URL |
Author restricted downloads |
Download manually from CurseForge website |
| Description empty |
Enrichment API call failed |
Non-critical — plugin still works |
Provider: Modrinth / Plugins (Detailed)
Overview
No configuration required. Server-side focused plugins.
Technical Details
| Property |
Value |
| API Base |
https://api.modrinth.com/v2 |
| Auth |
None required |
| Facets |
[["project_type:plugin"], ["categories:bukkit","categories:spigot","categories:paper"]] |
| Loaders filter |
["bukkit","spigot","paper"] |
| Download |
Direct URL from files[0].url |
Dependency Resolution
dependency_type === 'required' → auto-install- Direct
version_id → exact version
- No version_id → search latest compatible
Modrinth-Specific Errors
| Error |
Cause |
Solution |
| No results |
API temporarily unavailable |
Check status.modrinth.com |
| Empty version list |
No server-side versions for your MC version |
Try different version filter |
| Download failed |
CDN URL expired |
Clear cache, search again |
Provider: PaperMC / Hangar (Detailed)
Overview
No configuration required. Version-agnostic — no MC version filter.
Technical Details
| Property |
Value |
| API Base |
https://hangar.papermc.io/api/v1 |
| Auth |
None required |
| Plugin ID format |
owner/slug (e.g., ViaVersion/ViaVersion) |
| Platform priority |
PAPER → VELOCITY → WATERFALL (or specified variant) |
Download Types
| URL Type |
Behavior |
downloadUrl (internal) |
Direct download — installs normally |
externalUrl |
External link — sets requires_manual_download: true |
Dependency Resolution
pluginDeps with required: true → auto-install- Only Paper platform dependencies resolved
Hangar-Specific Errors
| Error |
Cause |
Solution |
| Plugin not found |
Wrong owner/slug format |
Plugin ID must be owner/slug |
| External download |
Author uses external hosting |
Download manually from linked site |
| Wrong platform |
VELOCITY plugin on PAPER server |
Check platform tags |
Provider: GeyserMC (Detailed)
Overview
No configuration required. 6 hardcoded projects with special download handling.
The 6 GeyserMC Projects
| Project |
Description |
Download Key |
| Geyser |
Bedrock-to-Java bridge |
spigot |
| Floodgate |
Bedrock auth integration |
spigot |
| Hurricane |
Performance optimizer |
spigot |
| GeyserConnect |
Server selector |
spigot |
| ThirdPartyCosmetics |
Cosmetics support |
spigot |
| EmoteOffhand |
Emote offhand fix |
spigot |
Technical Details
| Property |
Value |
| API Base |
https://download.geysermc.org/v2 |
| Version ID format |
{version}-{build} (e.g., 2.4.0-670) |
| Icon |
Base64 SVG island icon — same for all projects |
| Download counts |
Hardcoded (API doesn't provide them) |
| Metadata cache |
24 hours per project |
GeyserMC-Specific Notes
- Version-agnostic — no MC version filter shown in UI
- Downloads bypass
DaemonFileRepository::pull() entirely
- Uses direct cURL download to temp file → upload via
DaemonFileRepository::putContent()
- Custom User-Agent header sent
- No dependency API — dependencies must be installed manually
- Display name is capitalized project name
GeyserMC-Specific Errors
| Error |
Cause |
Solution |
| "GeyserMC download failed" |
CDN unreachable or network error |
Check download.geysermc.org accessibility |
| Wrong build |
Old metadata cached |
Wait 24 hours or clear cache |
| Plugin doesn't load |
Missing Geyser if installing Floodgate |
Install Geyser first — it's a dependency |
Cache Behavior
Cache Prefix: MP_
| What's cached |
TTL |
Key Pattern |
| Browse results |
15 min |
browse_plugins__{uuid}__{provider}__{version}__{md5}__{page} |
| Installed plugins list |
10 min |
plugins_server_{uuid} |
| Version lists |
1 hour |
plugin_versions_cache_{uuid}_{provider}_{pluginId} |
| Update metadata |
24 hours |
plugin_update__{uuid}__{pluginId} |
| Detected MC version |
5 min |
minecraft_version_{uuid} |
| Enriched installed data |
24 hours |
minecraft_plugins__{uuid} |
| Widget update check |
15 min |
plugin_updates_{uuid} |
| Server plugin filenames |
1 hour |
server_{uuid}_plugin_filenames |
SafeCacheService: File-based, prefix MP_, auto-creates directories with 0755, tracks all keys for flush.
Search Behavior
Query Sanitization
Characters < > { } ' " are removed from all search queries. Version filter validated against \d+\.\d+(\.\d+)? regex.
Search Retry on Failure
If a search with version filter returns zero results, the plugin automatically retries without the version filter — expanding results to all versions.
Troubleshooting
Settings don't save
- Check
storage/ directory write permissions
php artisan config:clear- Check browser console (F12) for JS errors
Cache won't clear
- SafeCacheService
flush() iterates all tracked keys
- If
storage/framework/cache/ missing or not writable → cache operations fail
- Error notification shows
$e->getMessage()