Porta VM Troubleshooting Playbook

This page is a symptom-driven troubleshooting playbook for a Porta On Prem deployment running on Porta VM. Each section is keyed by a common symptom, then describes the likely cause and the recovery steps.

• For a top-to-bottom check to run first, see the Porta VM Support Checklist.
• For a reference of where logs and configuration live, see the Porta VM Diagnostics Cheatsheet.

VM lifecycle issues

The VM’s IP address is shown as 127.0.0.1

This means VirtualBox isn’t connected to the correct network adaptor, or DHCP isn’t working on the chosen adaptor.

1. Shut down the VM if it is running.

2. On the Windows host, open PowerShell and run ipconfig /all to list all adapters and their names. Note any adapter that shows a real IPv4 lease.

3. In VirtualBox, open the VM’s Settings → Network. Confirm:

   • “Attached to” is set to Bridged Adapter.
   • “Name” matches an adapter from step 2 (often labelled d3net).

4. Start the VM, log in at the VirtualBox console as portavm, and check the IP with:

   ~/scripts/vm_info.sh

“Failed to establish SSH connection” during setup_vm.ps1

The cause depends on which step the failure occurred at. The setup script reports the step in the error message.

• During Network Configuration, with the IP shown as 127.0.0.1, see The VM’s IP address is shown as 127.0.0.1 above.
• During Resetting Identity, the SSH host key for the IP may be cached, or the SSH session dropped during the reboot. After the VM is back up, manually reset identity from the VirtualBox console: see Manually Resetting the Identity of a Porta On Prem VM.
• During Setting Static IP Address, set the static IP manually from the VirtualBox console: see Manually Setting Up a Static IP.

Warning

The setup_static_ip.sh script must be run from the VirtualBox console, not over SSH. The SSH session will drop when networking restarts and the setup will fail mid-flight.

ACPI shutdown takes longer than three minutes

This usually means the VM’s OS is stuck or under-resourced.

1. In the VM’s terminal window, choose File → Close → Power Off Machine.
2. Once the terminal closes, start the VM again from VirtualBox.
3. If this recurs, check the VM’s RAM and CPU allocation. The minimum is 8 GB and 4 vCPU.

Timed out waiting for the VM to come online

This message is common during the identity-reset and static-IP setup reboots. The setup script’s wait window is shorter than some VMs need.

1. Gracefully shut down the VM.
   • In the VM’s terminal window, choose File → Close → ACPI Shutdown.
   • If ACPI hangs, use Power Off Machine instead.
2. In the Powershell window, press Ctrl+C to stop the setup script.
3. Re-run setup_vm.ps1.
4. When prompted to import a new Porta VM or use an existing one, type 2 and press Enter.
5. Select the VM you previously imported.
6. Continue from the network configuration step.

”rcu: detected stalls on CPUs/tasks” appears in the VM terminal

This message indicates the VM is resource-starved.

1. Gracefully shut down the VM with File → Close → ACPI Shutdown, or Power Off Machine if ACPI hangs.
2. In VirtualBox Settings → System, confirm the VM has at least:
   • 8 GB RAM
   • 4 vCPU
   • A CPU that supports AVX2
3. Start the VM and monitor for recurrence.

If the message returns regularly, the host machine is under-provisioned for Porta VM. Consider allocating more resources or moving the VM to a more capable host.

The VM is stuck on “Begin: Loading essential drivers” at boot

The storage controller has lost the solid-state-drive hint, or VirtualBox’s storage configuration has drifted after a package update.

1. Shut down the VM.
2. In VirtualBox Settings → Storage, click the SATA virtual disk.
3. Check both of the following:
   • Solid-state Drive
   • Use host I/O cache
4. Start the VM.

VirtualBox shows “E_INVALIDARG 0X80070057” when importing the .ova

The drive holding VirtualBox’s default machine folder doesn’t have enough free space.

1. In VirtualBox, go to File → Preferences → General.
2. Change “Default Machine Folder” to a drive with enough space.
3. Run the VM setup again.

Static IP setup reported a failure but SSH actually works

This is a known false-positive warning in some Porta VM setup script versions.

Verify directly:

~/scripts/static_ip_info.sh

• If a static IP is configured and the VM is reachable at it, the warning was incorrect — carry on.
• If the static IP was not actually set, run ~/scripts/setup_static_ip.sh from the VirtualBox console.

The static IP wizard picked an unexpected subnet

The wizard infers the subnet from the existing DHCP configuration, which can be wrong on complex networks.

Use the manual-entry option in the wizard, or follow Manually Setting Up a Static IP from the VirtualBox console. Confirm the correct subnet with your IT team if there is any uncertainty.

VM IP changed and Porta is broken

A VM IP change is the most common root cause for live incidents on Porta VM. Multiple symptoms can all trace back to this:

• Porta can’t reach the database.
• The Porta UI shows the database status as red.
• Porta Bridge can’t connect.
• Engine clients (Unreal, Designer) can’t reach Porta.

The canonical recovery procedure is in Changing the IP of Porta On Prem. The summary below highlights the parts most often missed.

Recovery summary after an IP change

1. From the VirtualBox console (not SSH), reconfigure the VM’s static IP:

   Using the native VirtualBox terminal window of the running virtual machine, log in to the VM:

   • Type the username portavm and hit Enter,
   • Type the password provided to you and hit Enter again to log in.

   Then run:

   sudo ./scripts/disable_static_ip.sh
   sudo reboot

   When the VM is back up, log in again and run:

   sudo ./scripts/setup_static_ip.sh

2. In Porta Manager → Porta Configuration Management → Machines, edit each machine’s IP to the new value and click Save Changes.

3. On the Porta Manager dashboard, click Fix IP Settings and confirm.

4. Wait for the success message.

5. Refresh Porta in the browser.

Porta application surface

The browser shows an old Porta version after an update

The browser has cached the old version.

1. Hard-reload the page with Ctrl+Shift+R.

2. If that doesn’t help, clear all cookies and site data for the Porta origin, then reload.

3. Verify the backend version inside the VM:

   porta_check_version

   If the backend reports the new version, the update succeeded and the browser is the only thing stuck.

Login fails with “500 Internal Server Error” or “Could not create token: Key provided is shorter than 256 bits”

The JWT secret is empty or too short. This commonly happens after a .env edit or a partial install.

1. Inside the VM, run the following against the porta container:

   docker exec -it porta bash -c "php artisan cache:clear && php artisan jwt:secret && php artisan config:cache"

2. Clear the browser cookies for the Porta origin.

3. Try logging in again.

The socket server can’t reach Redis (“ECONNREFUSED 127.0.0.1:6379”)

The socket container started before Redis was ready, or Redis was restarted while the socket server held an open connection.

1. Stop the socket server container:

   docker stop porta-socket

2. Restart Redis and wait a few seconds:

   docker restart porta-redis

3. Start the socket server again:

   docker start porta-socket

Disk and resources

”No space left on device” or the VM is running slowly

1. Check disk usage:

   check_diskspace

2. Check what Docker can reclaim:

   docker_disk_usage

3. If “Images Reclaimable” is significant, remove unused images. Volumes are preserved:

   docker image prune -af

4. If / is still tight after step 3, the virtual disk needs to be enlarged. This is a VirtualBox-side operation (Virtual Media Manager, resize the .vdi) plus an in-VM resize chain using parted, pvresize, lvextend, and resize2fs. Contact Disguise support — partition resizing is hard to reverse and best done with engineering guidance.

High memory usage on the VM

1. Confirm the host’s allocation in VirtualBox Settings → System → Motherboard → Base Memory is at least 8 GB. 16 GB is recommended for larger deployments.

2. Inspect per-container memory inside the VM:

   docker stats

   porta-db is normally the heaviest container.

Designer, Unreal, and Porta Bridge connections

The configuration values for these integrations change with every IP change. Confirm the following in order:

Porta Bridge can’t connect to Porta

1. Confirm only one Porta Bridge instance is running on the Windows host. Check both the Windows system tray and Task Manager. Kill duplicates and restart Bridge.
2. In Bridge → Window → Porta, confirm:
   • Socket Server URL: http://<VM-IP>:6001.
   • API URL: http://<VM-IP>:8000.
3. Confirm Bridge HTTP Listener IP Address is the Windows host’s IPv4, not the VM’s IPv4.
4. Confirm the Windows firewall on the Bridge machine has port 1500 open for inbound traffic.
5. If using porta-socket.server or porta.server, confirm the Bridge machine’s Windows hosts file maps them to the VM’s current static IP.

Designer integration is not working

1. Confirm Designer is running.
2. Confirm the active Designer project matches the page, template, or channel that Porta is configured to use.
3. Verify Bridge is healthy. If Bridge is down, Designer’s integration will fail.

Porta Manager and the Installer Wizard

Porta Manager is unreachable at port 88

1. Check the container status:

   docker ps -a

2. If porta-manager-app has exited, view its logs:

   docker logs porta-manager-app

3. Recover non-destructively by recreating from existing images:

   mngr_recreate

4. If that fails, contact Disguise support.

”MAC Invalid” or “Invalid MAC” errors after a Porta Manager update

The APP_KEY in the running container differs from the key the data was encrypted with. Manager updates back up the relevant config automatically, so this should be rare.

1. Restore the preserved env file:

   mngr_restore_env

2. Recreate the Manager containers:

   mngr_recreate

Disaster recovery

For the full backup and restore procedures — including how automatic backups work, how to take a manual backup, single-node recovery, multi-node recovery, Unreal Engine failover, and VirtualBox snapshot rollback — see Porta VM Disaster Backup and Restore.