Troi File Plug-in: Essential Features & First-Time Setup Guide

Troubleshooting the Troi File Plug-in: Common Issues and Fixes

The Troi File Plug-in is a powerful FileMaker extension for file-system access and automation. When it misbehaves the result is usually broken scripts, permission errors, or unexpected behavior. This guide lists common issues, diagnostic steps, and concrete fixes so you can get back to work fast.

1. Plug-in not loading in FileMaker

Symptoms: plug-in absent from the list, functions return #ERROR, or FileMaker shows a missing plug-in alert.

Fixes:

• Verify installation: Ensure the Troi File Plug-in file (.fmx/.fp7/.fmx64 depending on platform and version) is placed in FileMaker’s Extensions/Plugins folder. Restart FileMaker after copying.
• Check compatibility: Confirm the plug-in version supports your FileMaker version and OS (32-bit vs 64-bit). Upgrade the plug-in if necessary.
• Permissions: On macOS, right-click the plug-in, choose Open once to bypass Gatekeeper if macOS blocks it. Ensure the user account has read & execute permissions on the plug-in file.
• License/activation: Some Troi plug-ins require activation. Open the plug-in manager in FileMaker and confirm license status.

2. Functions return errors or unexpected results

Symptoms: function calls produce #ERROR, empty results, or incorrect data.

Fixes:

• Syntax & parameters: Double-check function names and parameter order. Consult Troi’s function reference for exact signatures.
• File paths: Use absolute paths or use FileMaker’s Get ( DocumentsPath ) to construct reliable paths. On macOS use POSIX paths; on Windows use backslashes or convert them properly.
• File existence: Use Troi functions to test file existence before operations. If a file is missing, confirm the path and that the file hasn’t been moved or deleted.
• Encoding & line endings: When reading/writing text files, specify the correct encoding (UTF-8 vs ANSI) to avoid garbled text.

3. Permission denied / Access errors

Symptoms: operations fail with permission-related messages or files aren’t created/modified.

Fixes:

• File-system permissions: Ensure the FileMaker process user has write/read permissions on the target folder. On macOS and Linux check ownership and chmod; on Windows check NTFS permissions.
• Sandboxing / App Translocation (macOS): If FileMaker was downloaded and is translocated, it may not have expected access. Launch FileMaker from its final application location and restart.
• Antivirus or endpoint protection: Temporarily disable or add exceptions for FileMaker and the target folder to see if security software is blocking file access.
• Network shares: For files on network volumes, confirm the account has appropriate network permissions and that drives are mounted with expected paths.

4. Slow performance or timeouts with large files

Symptoms: file operations take long, scripts time out, or FileMaker becomes unresponsive.

Fixes:

• Process in chunks: For large reads/writes, process the file in smaller blocks rather than loading the entire file into memory.
• Asynchronous handling: Where possible, run heavy file operations in a scheduled/queued background script rather than the UI thread.
• Increase script timeouts: Adjust FileMaker script timeout settings or design longer-running tasks as server-side scripts on FileMaker Server.
• Use proper functions: Some Troi functions are optimized for specific use cases (binary vs text). Choose the one suited for your data.

5. Issues with network paths and UNC paths

Symptoms: functions work locally but not with \server\share paths or mounted network volumes.

Fixes:

• Use UNC paths on Windows: Use full UNC paths (\server\share\folder\file) rather than mapped drive letters when running under different service accounts.
• Mounting consistency (macOS): Ensure network shares are mounted under the same user context that runs FileMaker. Use automounts or login scripts if necessary.
• Credentials: When accessing protected shares, ensure credentials are provided or that the FileMaker process runs under a user with access.
• File locks: Networked files may be locked by other users—check for locks and coordinate access.

6. Cross-platform path and newline inconsistencies

Symptoms: scripts that worked on one OS fail or produce odd files on another OS.

Fixes:

• Normalize paths: Build paths using OS-aware functions or detect OS via Get ( SystemPlatform ) to format correctly.
• Line endings: When writing text files that will be consumed on another OS, normalize to CRLF for Windows or LF for Unix/macOS as required.
• Test on both platforms: If deploying to mixed environments, test key file workflows on each OS.

7. Plug-in crashes or causes FileMaker instability

Symptoms: FileMaker freezes, crashes, or the plug-in causes unexpected quits.

Fixes:

• Update plug-in & FileMaker: Install the latest Troi plug-in and FileMaker updates—many crashes are fixed in later releases.
• Reproduce minimal case: Isolate a minimal script or call that reproduces the crash and report it to Troi with steps to reproduce and sample files.
• Disable conflicting plug-ins: Temporarily disable other plug-ins to rule out conflicts.
• Collect logs/crash reports: On macOS use Console and crash logs; on Windows collect Event Viewer entries and any FileMaker crash logs for Troi support.

8. Licensing and activation problems

Symptoms: plug-in shows unlicensed, trial expired, or activation fails.

Fixes:

• Check license keys: Verify you entered the correct key in the plug-in preferences. Copy/paste to avoid typing errors.
• Firewall/activation server: Ensure the machine can reach Troi’s activation servers; temporarily allow outbound connections for activation.
• Reinstall & retry: Remove the plug-in, restart FileMaker, reinstall, and re-enter the license if needed.
• Contact Troi support: Provide license details and environment info if activation still fails.

Diagnostic checklist (quick)

• Restart FileMaker and the host machine.
• Confirm plug-in file is in the correct folder and visible in the Plug-in Manager.
• Verify plug-in version compatibility with FileMaker and OS.
• Test simple function calls with known-good paths and files.
• Check file/folder permissions and network mount status.
• Update plug-in and FileMaker to latest supported versions.
• Gather logs/crash reports before contacting support.

If you want, I can generate a short test script with Troi function calls tailored to your FileMaker version and OS to help reproduce or diagnose a specific error—tell me your FileMaker version and OS.