Skip to content
Disguise User Guide

Porta On Prem Installation Troubleshooting

Installation/Update Troubleshooting

Database Replication

For database troubleshooting, see group-replication-troubleshooting.

During Installation: SQLSTATE[HY000] [1130] Host '172.18.0.1' is not allowed to connect to this MySQL server at the migration step

Thu Dec 12 13:14:20 PST 2024: ERROR: Error occurred in command: 'docker exec -it porta bash -c "php artisan config:cache && yes | php artisan migrate && yes | php artisan db:seed --class=PermissionSeeder"' (Exit Code: 1) at line 47

This error may occur after a failed or aborted installation. It usually indicates that MySQL did not finish properly setting up.

  • Verify this by trying to run the porta-run/access-mysql.bat helper. If this fails, then there is no porta user and MySQL is misconfigured.

For existing installations, try running update.bat again. If this is a new installation that has not yet been used, try fully re-installing Porta from install.bat again.

Installation Aborts because Container 'porta-socket' did not become ready within the timeout.

This error can occur when the socket server container is not able to start up in time, without being caused by any particular errors. Re-run the install/update script and it should complete successfully.

Porta Version listed in the About section does not appear to have changed

It could be that the browser is caching the old version. If refreshing the browser does not resolve the issue, try clearing the browser cache and then refreshing the page.

In Chrome:

  • Click on the browser address bar (Porta disables some default keyboard shortcuts in the browser)
  • Hit Ctrl+Shift+Delete
  • Under the basic tab,
    • select “All time” for the time range
    • check the box for “Cookies and other site data”
  • Click “Clear data”
  • Refresh the page

To check against the version registered in the Porta backend, run the following helper: "porta-onprem-bundle\porta-helpers\porta-checks\check-version.bat"

If this version is correct, then the update was successful and the browser is just caching the old version information.

SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'superadmin@disguise.one' for key 'users.users_email_unique'

This error usually occurs when the install script is run more than once on the same machine. Operation should not be affected and you may continue the installation steps as normal.

Illuminate\Database\QueryException - SQLSTATE[HY000] [2002] Connection refused

Sometimes the database is not finished running/configuring before the install script tries to make changes to it. In this case, just run the following commands in the WSL terminal:

For first time installs: set the config and initialize the database & Run data insert:

  1. Run the config cache helpers: porta-onprem-bundle\porta-helpers\porta-run\cache-api-config.bat
  2. Run the seed helper: porta-onprem-bundle\porta-helpers\porta-database\actions\caution\migrate-or-seed.bat
    1. Enter or confirm the Windows user when prompted.
    2. Enter or confirm the WSL user when prompted.
    3. Answer “y” for Should the database be migrated?.
    4. Answer “y” for Should the database be seeded?.

For updates: set the config and initialize the database:

  1. Run the config cache helpers: porta-onprem-bundle\porta-helpers\porta-run\cache-api-config.bat
  2. Run the seed helper: porta-onprem-bundle\porta-helpers\porta-database\actions\caution\migrate-or-seed.bat
  3. Enter or confirm the Windows user when prompted.
  4. Enter or confirm the WSL user when prompted.
  5. Answer “y” for Should the database be migrated?.
  6. Answer “n” for Should the database be seeded?.

The command ‘docker’ could not be found in this WSL 2 distro

If you see this error along with 'ERROR: Error occurred in command: 'docker load -i "$PORTA_IMAGES_TAR"' (Exit Code: 1) at line 39'

  • Make sure Docker Desktop is running; you should be able to see the Docker icon in the taskbar or system tray.
    • If it appears to be running, it could be in resource-saver mode. In the system tray, right-click the Docker icon and select “restart”, then try again.

If the above does not work, make sure Ubuntu 22.04 is set as your default Linux distro: Porta Local Development Setup | Set default distro

Warning: Redis connection could not be made to ‘redis://localhost:6379’ : Error: connect ECONNREFUSED 127.0.0.1:6379

  1. Stop the Socket Server container with porta-helpers/porta-run/sysadmin/stop-container.ps1 and select the porta-socket container.
  2. Ensure the Redis container is started with porta-helpers/porta-run/sysadmin/restart-container.ps1 and select the porta-redis container.
  3. Once the Redis container is running, start, or restart, the Socket Server container with porta-helpers/porta-run/sysadmin/restart-container.ps1 and select the porta-socket container.

line 2: $'\r': command not found or /bin/bash^M: bad interpreter: No such file or directory

This is caused by windows line endings in the bash scripts. Run the helper porta-helpers/porta-run/sysadmin/fix-crlf.bat and try again.

ERROR 3093 (HY000) at line 1: The group_replication_group_name cannot be changed when Group Replication is running

This error can occur when running the install script on a machine that has already been set up as a Porta machine.

Simply restart the database container using the helper porta-helpers/porta-run/sysadmin/restart-container.ps1 and selecting the database container. Then view the container’s logs to ensure replication starts correctly by using the helper /porta-helpers/porta-database/follow-database-log.bat. You should eventually see a message like:

[System] [MY-011490] [Repl] Plugin group_replication reported: 'This server was declared online within the replication group.'

If this occurs on the main machine, you may also need to seed the database. Check to see if any users are registered by using the helper porta-helpers/porta-database/view-database-users.bat. If the results are empty, seed the database by running the seed helper and enter “y” for migration and seed: porta-onprem-bundle\porta-helpers\porta-database\actions\caution\migrate-or-seed.bat

If this is the main machine and the results are empty, seed the database by running the seed helper: porta-onprem-bundle\porta-helpers\porta-database\actions\caution\migrate-or-seed.bat

  1. Enter or confirm the Windows user when prompted.
  2. Enter or confirm the WSL user when prompted.
  3. Answer “n” for Should the database be migrated?.
  4. Answer “y” for Should the database be seeded?.

SQLSTATE[HY000]: General error: 1290 The MySQL server is running with the —read-only option

If this error is displayed in the Porta web app, then this instance of Porta is not connected to the primary database. It’s possible for this issue to occur if a database has recently gone down and Porta has not yet recovered, or if no primary was bootstrapped.

Porta should automatically recover within a few seconds, however, if it does not, you can take the following steps:

  1. Using helper porta-helpers/porta-database/view-ALL-group-repl-status.bat, view group members and make sure that:

    • at least two members have a MEMBER_STATE of ONLINE
    • only one member has MEMBER_ROLE of PRIMARY
    • the member with MEMBER_ROLE of PRIMARY has MEMBER_STATE of ONLINE

    Running the helper will result in something like:

    Terminal window
    +---------------------------+--------------------------------------+----------------+-------------+--------------+-------------+----------------+----------------------------+
    | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST    | MEMBER_PORT | MEMBER_STATE | MEMBER_ROLE | MEMBER_VERSION | MEMBER_COMMUNICATION_STACK |
    +---------------------------+--------------------------------------+----------------+-------------+--------------+-------------+----------------+----------------------------+
    | group_replication_applier | 1a351ce3-ba19-11ee-9e59-0242ac120002 | 192.168.50.163 |        3306 | ONLINE       | PRIMARY   | 8.0.32         | XCom                       |
    | group_replication_applier | d7c0535c-ba19-11ee-9f28-0242ac140002 | 192.168.50.20  |        3307 | ONLINE       | SECONDARY   | 8.0.32         | XCom                       |
    | group_replication_applier | e4a0ac63-ba19-11ee-9f54-0242ac150002 | 192.168.50.42  |        3308 | ONLINE       | SECONDARY     | 8.0.32         | XCom                       |
    +---------------------------+--------------------------------------+----------------+-------------+--------------+-------------+----------------+----------------------------+

  2. If there is no member with MEMBER_ROLE of PRIMARY, then you will need to Bootstrap the Replication Group as explained in the Replication Group Member Recovery documentation.

  3. If the error is still occurring even after the view-ALL-group-repl-status.bat helper is reporting a member with MEMBER_ROLE of PRIMARY and MEMBER_STATE of ONLINE, then check the database logs for errors by running the helper porta-helpers/porta-database/view-database-log.bat.

  4. If there are no recent errors, see if Porta is detecting the primary connection correctly on the problem machine by running the helper porta-helpers/porta-checks/check-primary-connection.bat

    This will result in something like:

    Terminal window
    Running health check...
    

    Running check: Primary Database Connection...
    Ok: Found online primary: {"member_host":"192.168.50.163", member_port":3306}
    

    All done!

  5. If the above command returns Ok: Found online primary... and the member_host displayed by the command matches the MEMBER_HOST from the view-ALL-group-repl-status helper above, then the issue is likely that Porta’s active connection is not being set to the primary connection.

  6. To check Porta’s active connection, run the helper porta-helpers/porta-checks/check-env-connections.bat

    This will result in something like:

    DB_HOST_1=192.168.50.163
    DB_HOST_2=192.168.50.20
    DB_HOST_3=192.168.50.42
    DB_HOST="${DB_HOST_3}"

    The DB_HOST variable should be set to the primary database’s DB_HOST_# variable.

    In this example, the primary database has a MEMBER_HOST of 192.168.50.163, which is the value of DB_HOST_1. So DB_HOST should actually be set to DB_HOST_1 and not DB_HOST_3.

  7. Cross-reference this with the default connection cached in the configuration with the helper porta-helpers/porta-checks/check-default-connection.bat.

    This will result in something like:

        'database' =>
      array (
        'default' => 'mysql-3',

    The numeric suffix of the value of 'default' => should match the suffix of the DB_HOST_# variable that DB_HOST is set to.

    In this example, they’re both 3, so the configuration is cached correctly, but is not set to the primary connection

Your initial run of check-primary-connection.bat should have triggered a connection change to the primary database.

When running backup tool command: Backup failed because Parameter 'host' cannot be empty...

This error can occur when running the backup tool command on a machine that does not have its configuration cached.

To fix this, run the helper porta-helpers/porta-run/cache-api-config.bat

Running the backup tool command again should now work.

Error on Login: “500 Internal Server Error” / “Could not create token: Key provided is shorter than 256 bits”

If you get this generic error, you may need to generate a new token secret using the helper porta-helpers/porta-run/sysadmin/generate-secret.bat

Then try logging in to Porta again.