Troubleshooting

Common Issues

Missing Required Properties

Symptom: MCReleaser exits immediately without uploading Error Message:

ERROR: The following keys are missing: name, version, description

Cause: Required properties are not set in environment variables or system properties. Solution:

Ensure all required properties are set:

export NAME="My Mod"
export VERSION="1.0.0"
export DESCRIPTION="Release description"
export FILES="build/libs/*.jar"

Or use system properties:

java -Dname="My Mod" \
     -Dversion="1.0.0" \
     -Ddescription="Release description" \
     -Dfiles="build/libs/*.jar" \
     -jar mcreleaser.jar

Enable missing key announcements to see what’s missing:

export ANNOUNCE_MISSING_KEY=true
java -jar mcreleaser.jar

Required properties: name, version, description, files

No Platform Found

Symptom: Runtime exception Error Message:

java.lang.RuntimeException: No platform found

Cause:

platforms property is empty or invalid
Platform-specific required properties are missing
Platform names are misspelled

Solution:

Check platform names (must be lowercase):

# Valid platforms
export PLATFORMS="github,modrinth,curseforge,hangar,polymart"

# Or use all platforms
export PLATFORMS="all"

Verify platform-specific properties are set:

Modrinth:

export MODRINTH_TOKEN="mrp_xxxxx"
export MODRINTH_PROJECT="my-mod"

GitHub:

export GITHUB_TOKEN="ghp_xxxxx"
export GITHUB_REPOSITORY="owner/repo"

CurseForge:

export CURSEFORGE_TOKEN="xxxxx"
export CURSEFORGE_PROJECT="123456"

Hangar:

export HANGAR_TOKEN="xxxxx"
export HANGAR_PROJECT="owner/project"

Polymart:

export POLYMART_TOKEN="xxxxx"
export POLYMART_PROJECT="12345"

File Globs Not Found

Symptom: Validation error Error Message:

java.lang.IllegalStateException: File globs not found

Cause: The files property is not set. Solution:

export FILES="build/libs/*.jar"
# Or multiple patterns
export FILES="build/libs/*.jar build/libs/*-sources.jar"

Use space-separated glob patterns to match multiple files. Globs are resolved relative to the current working directory.

Authentication Failures

Symptom: HTTP 401 or 403 errors Error Message (varies by platform):

Unauthorized: Invalid token
Forbidden: Insufficient permissions

Cause: Invalid or expired authentication tokens Solution:

Verify token format:

Modrinth: Tokens start with mrp_
GitHub: Personal access tokens start with ghp_, fine-grained tokens start with github_pat_
CurseForge: API key from CurseForge console
Hangar: API key from Hangar settings
Polymart: API key from Polymart account

Check token permissions:

GitHub: Requires repo scope (or contents: write for fine-grained)
Modrinth: Requires PROJECT_WRITE scope
CurseForge: Requires project upload permissions

Regenerate tokens if expired or compromised
Verify environment variables are set correctly:

# Check token is set (without revealing value)
echo ${MODRINTH_TOKEN:0:4}...  # Should show 'mrp_'
echo ${GITHUB_TOKEN:0:4}...    # Should show 'ghp_' or 'gith'

Never commit tokens to version control. Use environment variables or CI/CD secrets.

Invalid Project ID

Symptom: HTTP 404 or project not found error Cause: Incorrect project identifier for the platform Solution:

Modrinth: Use project slug or ID

# Slug (from project URL)
export MODRINTH_PROJECT="my-mod"  # From modrinth.com/mod/my-mod

# Or project ID
export MODRINTH_PROJECT="AABBCCDD"

GitHub: Use owner/repository format

export GITHUB_REPOSITORY="username/repo-name"

CurseForge: Use numeric project ID

# From project URL: curseforge.com/minecraft/mc-mods/my-mod/files
# Look for project ID in API or project settings
export CURSEFORGE_PROJECT="123456"

Hangar: Use owner/project format

export HANGAR_PROJECT="username/project-name"

Polymart: Use numeric resource ID

export POLYMART_PROJECT="12345"

Game Version Errors

Symptom: Upload rejected due to invalid game versions Error Message:

Invalid game version: 1.20.5
Game version not supported by platform

Cause:

Game version format incorrect
Game version not yet available on platform
Version type filter too restrictive

Solution:

Use correct format (comma or space-separated):

export GAME_VERSIONS="1.20.1,1.20.2,1.20.4"
# Or space-separated
export GAME_VERSIONS="1.20.1 1.20.2 1.20.4"

Use version type filter to auto-fetch versions:

export GAME_VERSION_TYPE="release"  # Only release versions
export GAME_VERSION_TYPE="snapshot" # Only snapshots
export GAME_VERSION_TYPE="all"      # All versions

Override per platform:

# Global versions
export GAME_VERSIONS="1.20.1,1.20.2"

# Platform-specific override
export MODRINTH_GAME_VERSIONS="1.20.1,1.20.2,1.20.4"
export CURSEFORGE_GAME_VERSIONS="1.20.1,1.20.2"

Check platform availability: Some platforms may not have newer versions available immediately after Minecraft releases.

Platform-specific gameVersions properties override the global GAME_VERSIONS property.

Network Timeouts

Symptom: Upload hangs or times out Error Message:

java.net.SocketTimeoutException: Read timed out
Connection timeout

Cause:

Large file uploads on slow connections
Multiple parallel uploads overwhelming network
Platform API slowness

Solution:

Use synchronous mode to upload sequentially:

export SYNC=true
java -jar mcreleaser.jar

Reduce number of platforms:

# Instead of "all"
export PLATFORMS="modrinth,curseforge"

Check network connectivity:

# Test platform API endpoints
curl -I https://api.modrinth.com/v2
curl -I https://api.github.com

Increase Java timeout (if using custom HTTP client):

java -Dhttp.timeout=300000 -jar mcreleaser.jar  # 5 minutes

Partial Upload Success

Symptom: Some platforms succeed, others fail in async mode Cause: Asynchronous mode continues uploading to all platforms even if one fails Solution:

Check logs to identify which platform failed
Use synchronous mode for clearer error tracking:

export SYNC=true
java -jar mcreleaser.jar

Upload to single platform to isolate issue:

export PLATFORMS="modrinth"
java -jar mcreleaser.jar

Re-run for failed platforms only:

# First run uploaded to github and modrinth
# Second run targets only the failed platform
export PLATFORMS="curseforge"
java -jar mcreleaser.jar

In async mode, successful uploads are not rolled back if others fail. You may need to manually delete or hide failed releases.

Property Name Confusion

Symptom: Property not being read despite being set Cause: Incorrect property name casing or format Solution:

Use correct casing:

# Environment variables: CONSTANT_CASE
export MODRINTH_TOKEN="mrp_xxxxx"      # Correct
export modrinth_token="mrp_xxxxx"      # Wrong

# System properties: camelCase
java -DmodrinthToken="mrp_xxxxx"       # Correct
java -Dmodrinth-token="mrp_xxxxx"      # Wrong

Verify conversion:

Property (camelCase)	Environment (CONSTANT_CASE)
`modrinthToken`	`MODRINTH_TOKEN`
`gameVersionType`	`GAME_VERSION_TYPE`
`githubRepository`	`GITHUB_REPOSITORY`

Check priority: Environment variables override system properties

# This sets VERSION to "2.0.0" (env var wins)
export VERSION="2.0.0"
java -Dversion="1.0.0" -jar mcreleaser.jar

Dependency Format Errors

Symptom: Modrinth upload fails due to invalid dependencies Error Message:

Invalid dependency format

Cause: Incorrect dependency syntax Solution: Use correct Modrinth dependency format:

# Format: project-id:type
# Types: required, optional, incompatible, embedded
export MODRINTH_DEPENDENCIES="fabric-api:required,sodium:optional"

# Multiple dependencies (comma-separated)
export MODRINTH_DEPENDENCIES="fabric-api:required,fabric-kotlin:required,sodium:optional"

File Not Found

Symptom: Upload fails because files don’t exist Error Message:

No files found matching glob pattern

Cause:

Incorrect glob pattern
Files not built yet
Wrong working directory

Solution:

Verify files exist:

ls -la build/libs/*.jar

Check working directory:

pwd  # Should be project root
cd /path/to/project
java -jar mcreleaser.jar

Use correct glob pattern:

# Correct
export FILES="build/libs/*.jar"

# Exclude sources/javadoc
export FILES="build/libs/*[!-sources][!-javadoc].jar"

# Multiple patterns
export FILES="build/libs/*.jar *.zip"

Build before uploading:

# Gradle
./gradlew build
java -jar mcreleaser.jar

# Maven
mvn package
java -jar mcreleaser.jar

Debugging Tips

Enable Verbose Logging

MCReleaser uses SLF4J. Configure logging in logback.xml or via system properties:

java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar mcreleaser.jar

Check Property Values

Verify all properties are set correctly:

# Enable missing key announcements
export ANNOUNCE_MISSING_KEY=true
java -jar mcreleaser.jar

Test Single Platform

Isolate issues by testing one platform at a time:

export PLATFORMS="modrinth"
java -jar mcreleaser.jar

Use Synchronous Mode

Easier to debug with sequential execution:

export SYNC=true
java -jar mcreleaser.jar

Validate Tokens

Test API tokens independently:

# Modrinth
curl -H "Authorization: ${MODRINTH_TOKEN}" \
     https://api.modrinth.com/v2/user

# GitHub
curl -H "Authorization: token ${GITHUB_TOKEN}" \
     https://api.github.com/user

Check API Status

Verify platform APIs are operational:

Modrinth: https://status.modrinth.com
GitHub: https://www.githubstatus.com
CurseForge: Check community forums

Getting Help

If you’re still experiencing issues:

Check existing issues: Search the GitHub repository for similar problems
Gather information:
- MCReleaser version
- Java version (java -version)
- Full command or configuration
- Complete error message and stack trace
- Platform(s) affected
Create a minimal reproduction: Simplify to smallest failing case
Redact sensitive information: Remove tokens, project IDs, and other secrets
Open an issue: Provide all gathered information

Never include authentication tokens, API keys, or other secrets when requesting help publicly.

Best Practices to Avoid Issues

Use environment variables for secrets: Prevents accidental exposure
Enable missing key announcements during development: Catch configuration errors early
Test with single platform first: Verify configuration before multi-platform upload
Use version control for configuration: Track changes to .env files (exclude secrets)
Validate tokens regularly: Check expiration and permissions
Document your configuration: Maintain .env.example with required properties
Use CI/CD secrets management: Never hardcode tokens in scripts
Test in synchronous mode first: Easier debugging before switching to async

Create a test project on each platform for dry-run testing without affecting production releases.

Get Started

Installation

Configuration

Guides

Platform-Specific

Advanced

Common Issues

Missing Required Properties

No Platform Found

File Globs Not Found

Authentication Failures

Invalid Project ID

Game Version Errors

Network Timeouts

Partial Upload Success

Property Name Confusion

Dependency Format Errors

File Not Found

Debugging Tips

Enable Verbose Logging

Check Property Values

Test Single Platform

Use Synchronous Mode

Validate Tokens

Check API Status

Getting Help

Best Practices to Avoid Issues

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Guides

Platform-Specific

Advanced

​Common Issues

​Missing Required Properties

​No Platform Found

​File Globs Not Found

​Authentication Failures

​Invalid Project ID

​Game Version Errors

​Network Timeouts

​Partial Upload Success

​Property Name Confusion

​Dependency Format Errors

​File Not Found

​Debugging Tips

​Enable Verbose Logging

​Check Property Values

​Test Single Platform

​Use Synchronous Mode

​Validate Tokens

​Check API Status

​Getting Help

​Best Practices to Avoid Issues

Build docs developers (and LLMs) love

Common Issues

Missing Required Properties

No Platform Found

File Globs Not Found

Authentication Failures

Invalid Project ID

Game Version Errors

Network Timeouts

Partial Upload Success

Property Name Confusion

Dependency Format Errors

File Not Found

Debugging Tips

Enable Verbose Logging

Check Property Values

Test Single Platform

Use Synchronous Mode

Validate Tokens

Check API Status

Getting Help

Best Practices to Avoid Issues