Troubleshooting and FAQ

Troubleshooting and FAQ

Connecting to Jamf Pro

Connecting shows "Permission check blocked: … missing the "Read API Integrations" privilege" (or Read API Roles / Read Accounts). Magic Toolbox needs to read the account's own permissions to show the permission check. Add the privilege it names to the API role (for API clients) or to the account (for username and password). See Jamf API Permissions.

Permissions show Denied, but I know the account has them.

• Username & password accounts: privileges from local Jamf Pro account groups are included for Group Access accounts, but privileges from an LDAP group can't be read through the API. Click Proceed Anyway → (the actions will still work), or use an API client instead.
• API clients: check that the client is enabled and that the role is actually assigned to it. The app reads the privileges each time you connect, so after changing the role, go Back and connect again.
• Compare: its check makes a test request for each item. If Jamf Pro returns an unexpected error (anything other than success, forbidden or not found), the item is shown as Denied rather than assumed to be allowed. Connect again, or use Proceed Anyway → if you're sure the account has it.
• Jamf sometimes renames privileges between versions. If the tool works after Proceed Anyway →, you can ignore the warning.

I get "Authentication failed — please check your credentials."

This now only appears when Jamf Pro actually rejects the credentials. Other problems, such as a wrong URL or a server error, show what Jamf Pro returned.

• API client: check the Client ID and Secret, check the client is enabled, and make sure the secret hasn't been regenerated.
• Username & password: accounts that sign in only through SSO can't use the API directly. Use an API client.
• Check the server address. Just acme becomes acme.jamfcloud.com. For on-premises servers, include the port. The app always uses HTTPS, so the server needs a trusted certificate and TLS 1.2 or later.

The connection times out. Check that your Mac can reach the server (VPN, proxy, firewall). Each request times out after 30 seconds, and a network failure shows as "Network error: …".

A tool fails partway through on a large server. Very large servers can hit Jamf Pro API rate limits or time-outs. Requests that are rate-limited (429) or hit a busy server (503) are retried automatically a few times. If it still fails, run the tool again. Tools that only read are always safe to repeat. Turn on debug logging for the tool to see which request failed.

Licensing

See Licensing and Trial → Licence troubleshooting.

All the tools are locked and the window says Activate Magic Toolbox. The 72-hour trial has ended, or the licence was removed from this Mac. Enter your licence key. See Licensing and Trial.

A tool says its results are incomplete. Something couldn't be read, usually because of a missing read privilege or a network error. The message names what's missing. Fix it and run the tool again. Don't treat an incomplete result as an all-clear: Unused won't let you delete from an incomplete category for this reason.

The app

I can't go Home, switch tools or close the window. A tool is changing Jamf Pro (cloning, wiping, disabling, restoring, deleting or uploading). Wait for it to finish. Closing the window or quitting asks first, with Keep Running as the default.

A tool asks for a PIN. It's protected by Tool Lock. If you've forgotten the PIN, delete the toolLock.hashedPin item for com.mdmmagic.MagicToolbox in Keychain Access, which turns Tool Lock off.

The MDM Reporting Tool tile opens a web page. The app isn't set up, or can't be found. Choose it in Preferences → Third-Party Tools, or hide the tile there.

I closed the window and can't find the app. It's still running in the menu bar. Click the wand icon and choose Open Magic Toolbox.

How do I quit completely? Click the menu bar icon → Quit Magic Toolbox (⌘Q).

Where are my saved credentials? In the macOS Keychain, on this Mac only. Each tool saves its own, and only when Save credentials to Keychain is on. Use Saved Servers on the Home screen to share one set of credentials across all tools. See Getting Started → Saved Servers.

Drag and drop does nothing. Check the file type the tool accepts. Unsupported files are ignored. Inspector takes .pkg, .mpkg and .app. PPPC Analyser and Notifications take .app and .pkg. System Extensions takes .app, .systemextension, .dext and .pkg. Profile Signer and Profile Unsigner take .mobileconfig and .pkg. Web Content Filter and the Icons Extract from .app window take .app only. Disk images (.dmg) aren't supported anywhere: mount the image first and drop what's inside.

Tool questions

Is it safe to point Magic Toolbox at production? These tools are read-only and safe on production: Compare, Profile Conflicts, Smart Group Audit, Account Audit, Cert & Token Expiry, Downloader, the Icons scan, and the scan in Unused. Inspector, Network Check, Profile Signer and Profile Unsigner run only on your Mac and don't connect to Jamf Pro. These change Jamf Pro: Clone (destinations), Restore, Disable (disables policies, accounts and App Installers, and removes scope, straight away, which uninstalls profiles and apps from devices), deleting in Unused, uploads from the profile builders and Icons, and Wipe (never on production; use Dry run first).

Can Clone copy packages? No. Package files can't be transferred through the Jamf Pro API. Clone lists any missing packages so you can upload them yourself. See Clone.

Can I undo a Wipe? Only with the backup file, its passphrase and Restore. Restore creates new objects with new IDs. App Installers and Jamf Pro Accounts can't be restored. If you've lost the passphrase, the backup can't be opened.

Can I undo a Disable? Yes. Connect to the same server in Disable, click Undo from backup… and open the undo backup it saved, with its passphrase. See Disable.

Can I undo a Clone overwrite? Yes. Clone backs up each destination object before overwriting it. Open the Clone_Backup_*.json file in Restore and use Update existing objects.

Restore says "Incorrect passphrase, or the backup file is corrupt or has been tampered with." Check the passphrase, including capitals and spaces. The same message appears if the file was edited after it was saved, or if it isn't an encrypted Wipe, Unused or Clone backup. Plain JSON backups from older versions of Magic Toolbox can't be opened in Restore. A Disable undo backup opens in Disable, not Restore.

Can I undo a delete in Unused? Yes, with Restore. Unused saves an encrypted backup of the items before it deletes them. Open it in Restore with the passphrase you chose. Restored items get new IDs. See Unused.

My upload asks whether to overwrite a profile. A profile with the same name already exists in Jamf Pro. Overwrite updates it, Cancel leaves it alone. See Uploading Profiles.

Profile Signer says no signing certificate is selected, or it can't be found. Choose one in Preferences → Profile Signing Certificate, and click Refresh if a new certificate is missing from the list.

Does Magic Toolbox support Intune, Kandji/Iru, Mosyle or other MDMs? Magic Toolbox is built for Jamf Pro. The local tools (Inspector and the profile builders' .mobileconfig output) work with any MDM that accepts custom configuration profiles.

Where do I download Magic Toolbox? From the Releases page. Download the .pkg under Assets and run it to install Magic Toolbox.app. See Installation.

Reporting a bug

1. Turn on debug logging for the tool.
2. Reproduce the problem.
3. Open Preferences → Debug Logging → View Logs, click Copy, and remove anything sensitive.
4. Open an issue with:
   • your Magic Toolbox version (About (?)) and macOS version
   • your Jamf Pro version (and whether it's Jamf Cloud or on-premises)
   • the steps to reproduce, what you expected and what happened
   • the debug log