Help
Help and troubleshooting
Most problems have a short fix. If yours isn't here, ask on the Discord, or send a report from Settings › Report a problem. You can read the whole report before it goes anywhere.
Looking for an exact error message, a setting or an engine line? Search all the documentation.
Setting up
It says “Pairing file needed”
The pairing file lets Porthole switch JIT on. On iOS 27 or later, tap Create it on this device in the setup guide, then open Settings › Privacy & Security › Developer Mode › “Pair with Porthole” and type the six-digit code Porthole shows. On earlier versions of iOS the file is made once on a computer with a free pairing tool such as iloader or Jitterbug: plug the device in, tap Trust, save the pairing file, move it to the device and choose it in Porthole.
iOS asks to add a VPN. Is that safe?
Yes. It is not a real VPN: it is a small private link that exists only inside your device, so Porthole can reach your device's own debug service to switch JIT on. Nothing goes over the internet and none of your other traffic is touched. Tap Allow. iOS runs one VPN at a time, so another VPN app pauses for a few seconds; Porthole asks first and can help turn it back on.
JIT won't switch on, or the game doesn't start
Check these in order: the pairing file is there (setup guide, step 1); the private link is allowed; the app was signed with a development profile that includes get-task-allow (Porthole says so if it wasn't); and no debugger is attached (if you started the app from Xcode, close it and open Porthole from the Home Screen). Developer Mode must be on in Settings › Privacy & Security.
After updating Porthole, the tunnel says “connecting” and then “disconnected”
iOS sometimes keeps old information about the app's helper after an update. Restart the device. Your games and settings aren't affected, and you don't need to reinstall.
Can I use a free Apple ID?
Yes, with some features missing. A free account can't carry the Network Extension capability, so you run LocalDevVPN for the private link before you press Play, and it can't carry Increased Memory Limit, so memory-hungry games are more likely to run out of memory. Its signing also expires after about a week. A paid developer account or a third-party certificate service gives you the complete install. Settings › Stores and JIT › Your install shows what yours is missing.
My signing certificate or profile expired
Profiles run out: after about 7 days with a free Apple account and after about a year with a paid one. A third-party service can also revoke its certificate; sign again with a new one. Sign the app again with the same account (so iOS treats it as an update and keeps your games). You can also add your certificate and profile in Settings › Updates so Porthole signs its own updates on the device.
Playing
A game closes by itself or stutters
The device is probably running out of memory. Open the game's settings and raise Swap, which lets Porthole use storage as extra memory, and close other apps. The Stats button while you play shows how full swap is, and Porthole shows a warning when memory is nearly full. If it keeps happening, send a problem report: the log says why.
The first start takes a long time
The first start of a game sets everything up, and some games prepare their graphics as they run, so it can take a minute or more and the first frames may stutter. Keep Porthole open and the screen on while it loads. Later starts are quicker.
A Steam game won't start
Try the other way. Touch and hold the game on the Home screen and choose Run directly (skip Steam), or the reverse if it is already set to run directly. Some Unity games only work when started through Steam. If it still fails, read what Porthole can't run.
The game is too slow, or the device gets hot
Choose the power mode with the Power button in the in-game menu. Performance goes up to 120 FPS on iPads and iPhones with ProMotion screens but uses more battery and heat; Balanced and Battery saver do the opposite. The compatibility list shows what other people report for your model, which tells you what to expect.
My controller isn't picked up
Pair it first in iOS Settings › Bluetooth. If a game still doesn't see it, open the game's settings and try DualSense (HID) and Xbox (this fixed Hollow Knight: Silksong), or switch on Controller as keyboard and mouse. In HID mode rumble doesn't work. Each game's controller buttons can be remapped under Controller buttons.
My keyboard or mouse does nothing in a game
On an iPad, connect them before you start the game and run Porthole full screen (not in Split View or Stage Manager), which lets the pointer lock for looking around. If a click arrives as a finger tap, turn AssistiveTouch off in iOS Settings › Accessibility › Touch and restart Porthole. Porthole's menu opens with F10; you can change that key, the pointer lock key and the mouse speed in Settings › Advanced › Engine options › Keyboard and mouse. A game that turns the camera with the mouse but never hides its cursor needs “Always use the mouse to look” there. An iPhone gets a mouse only through AssistiveTouch and cannot lock the pointer. If it still fails, send a problem report (Settings › Report a problem); its log has lines starting [hwinput].
The on-screen controls disappeared
They hide while a controller is in use and come back when you touch the screen.
Stores and downloads
How do I sign in to itch.io?
itch.io uses a personal API key. In Porthole choose Sign in to itch.io, open the API keys page, sign in there, tap Generate new API key, copy it and paste it back. The key stays in your device's Keychain and is sent only to itch.io.
Epic Games and GOG show a sign-in page
That is the store's own page: you type your password there, so Porthole never sees it. Porthole keeps only a sign-in token. If a store refuses the sign-in, sign out in Porthole and sign in again.
A download is stuck, paused or failed
Open the round Downloads button at the bottom right of the Stores tab. It lists every store's downloads with Pause, Resume, Try again and Download now. Check that the device has free space (Settings › Storage shows what is using it). Downloads carry on when you leave the app.
Steam sign-in or downloads fail on one network only
Some work and school networks block Steam. Try another network or a mobile connection. If it works there, the network was the cause.
Reports and privacy
How do I report a problem?
Settings › Report a problem. Describe what went wrong and Porthole adds the log of the run. Tap Look at exactly what would be shared to read the whole report first. You can send it to the project's server or save it as a file and share it yourself. The privacy page lists exactly what is in it.
What is sent about me?
Nothing unless you choose to send a report. The privacy page lists everything, and the trust page says how your logins are protected.
Will the game fit in memory?
A game that wants more memory than your device has can't run. Slide to compare. This is a rule of thumb, not a promise: the same game can behave differently on your device.
Where to find the number: the game's store page lists its memory (RAM) requirement. Swap lets Porthole use storage as extra memory, which helps with tight fits, not impossible ones.
Didn't find it? Ask on the Discord or open an issue on GitHub.