Skip to main content

Troubleshooting

Common issues and their solutions.

Run EFM Diagnostics​

The first step for any issue: run the built-in diagnostics.

RunEFMDiagnostics()

Check the Output Log for pass/fail results for every EFM function.

Common Issues​

File Not Found​

Symptom: FileExists() returns false for a file you know exists.

Solutions:

  1. Check the path format - use NormalizePath() to fix mixed slashes
  2. Use GetAbsolutePath() to convert relative paths
  3. Verify the file actually exists at the expected location
  4. Check file permissions
// Debug the path
FullPath = CreateFullPath(Directory, Name)
Log("Looking for: " + FullPath)
Log("Normalized: " + NormalizePath(FullPath))
Log("Is absolute: " + IsAbsolutePath(FullPath))

Permission Denied​

Symptom: File operations fail with access errors.

Solutions:

  1. Don't write to protected directories (Program Files, etc.)
  2. Always use GetGameSavedDirectory() for runtime writes
  3. On Linux/Mac, check file ownership and permissions
  4. Run the editor as Administrator (Windows, for testing only)

JSON Read/Write Fails​

Symptom: ReadJsonFile() returns false or data is missing.

Solutions:

  1. For nested JSON, use ReadJsonFileNestedAsString() instead
  2. Check that the JSON is valid (use a JSON validator)
  3. ReadJsonFile() only supports flat key-value JSON objects
  4. Use WriteJsonFileNested() for nested structures
// Flat JSON works with ReadJsonFile
{"name": "Hero", "level": "42"}

// Nested JSON needs ReadJsonFileNestedAsString
{"player": {"name": "Hero", "stats": {"level": 42}}}

Download Fails​

Symptom: DownloadFile() always fails.

Solutions:

  1. Check that the URL is valid and accessible
  2. Verify the save directory exists before downloading
  3. Check firewall/antivirus settings
  4. Use GetRemoteFileSize() first to verify the URL works
// Test URL first
GetRemoteFileSize(Self, URL, OnComplete)
  OnComplete(bSuccess, URL, FileSize):
    if bSuccess:
      Log("File size: " + FileSize)
      // Now download
      DownloadFile(Self, URL, SavePath, OnProgress, OnDownloadComplete)
    else:
      LogError("URL not accessible: " + URL)

Async Operations Not Firing​

Symptom: Async callbacks never execute.

Solutions:

  1. Ensure the WorldContextObject is valid
  2. The calling object must not be garbage collected before the callback fires
  3. Check the Output Log for async errors
  4. Test with synchronous versions first to isolate the issue

ZIP Operations Fail​

Symptom: CompressFiles() or DecompressZip() returns false.

Solutions:

  1. Ensure the output directory exists before compressing
  2. Check that source files exist before compressing
  3. For decompression, ensure the destination directory is writable
  4. Use ListZipContents() to verify the ZIP is valid

Encryption/Decryption Mismatch​

Symptom: Decrypted data doesn't match original.

Solutions:

  1. Ensure the same key is used for encryption and decryption
  2. Don't modify the encrypted data between encrypt/decrypt
  3. Test with a simple string first to verify the key works
  4. Check that the key doesn't contain special characters that might be escaped

Platform-Specific Notes​

Windows​

  • Path separator: \ (but / also works)
  • Symlinks require Administrator privileges or Developer Mode enabled
  • File dialogs use native Windows dialogs

Linux​

  • Path separator: /
  • Case-sensitive file names
  • File permissions matter (use chmod if needed)

Mac​

  • Path separator: /
  • Case-insensitive by default (HFS+/APFS)
  • Sandboxing may restrict file access

Getting Help​

If the issue persists:

  1. Run RunEFMDiagnostics() and share the Output Log
  2. Check the GitHub Issues
  3. Email support: [email protected]
  4. Visit the author's website: simonecampitelli.com