Troubleshooting

Troubleshooting

php bin/self-check.php says Zip is missing

Install/enable the PHP Zip extension.

The server workspace requires Zip because it processes source ZIP archives and portable .spkg14 packages.

The health endpoint reports the same requirement.

/health.php returns 503 / degraded

Inspect the JSON response. Required checks include:

• PHP >= 8.2
• Sodium
• Zip
• random_bytes()
• writable/initializable storage

PDO MySQL is reported as optional in the current health endpoint.

Account registration fails with Unable to create account.

A common deployment issue is missing SPK_NAME_PEPPER in PHP's environment.

Current V14 behavior includes a fallback that generates:

storage/secrets/name-pepper.bin

with a random 256-bit value and restrictive permissions.

For production, configure an explicit secret instead of depending on the fallback.

Browser V13 says it cannot open a package it just created

V14.1.0 fixed a V13 builder/parser schema mismatch where key slots lacked the required type and version fields.

Verify that the deployed browser client contains:

primary:  type=password-pattern, version=1
recovery: type=recovery, version=1

Package restore fails after changing the ZIP manually

This is expected when authenticated metadata or ciphertext was modified.

V14 verifies:

• header binding
• manifest authentication
• completion record
• ciphertext hashes
• Merkle root
• stream authentication

A changed package is supposed to fail closed.

Restore says destination already exists

V14 intentionally uses a fail-on-existing-path restore policy.

Choose a new destination rather than allowing the application to overwrite an existing tree.

Unable to build package. after a large ZIP upload

Check the archive and V14 limits.

Relevant current limits include:

• upload: 1 TiB
• upload chunk: 8 MiB
• single input file: 16 GiB
• total archive plaintext: 100 GiB
• V14 total plaintext: 100 GiB
• V14 nodes: 100,000
• V14 blobs: 100,000

Also check available disk space and PHP process/resource limits.

Composer commands are unavailable

The runtime can still expose the application code, but the documented development/release gates use Composer.

Install Composer in the development/release environment before relying on:

composer validate --strict --no-check-publish
composer install --no-interaction --prefer-dist --no-progress
composer audit --no-interaction

Do not generate a fake lockfile just to satisfy CI.

Release verification warns about embedded-key verification

The verifier supports two trust modes.

Without an external key:

embedded-key verification

checks self-consistency only.

For independent trust, configure:

SECURE_PACKAGE_TRUSTED_RELEASE_KEY_HEX=<64-hex-public-key>

Recovery key was lost

The V14 recovery key is deliberately not recoverable from the package.

If the password/pattern is also unavailable, the package is intentionally designed to remain inaccessible.

This is a security property, not a missing convenience feature.

Temporary files remain after a crash

Use the cleanup helper and inspect the temporary storage tree:

php bin/cleanup.php

Operational environments should schedule cleanup of expired upload, job, access-token, and restore-token state according to their deployment model.

GitHub Actions or CI fails unexpectedly

Run the same checks locally where possible:

php bin/self-check.php
php bin/source-audit.php
php bin/security-test.php --full
composer validate --strict --no-check-publish
composer audit --no-interaction

Also verify that CI has PHP Zip enabled and that a real committed composer.lock exists for release-gated workflows.

Security issue disclosure

Do not publish sensitive exploit details in a public issue before coordinating responsible disclosure. The repository should maintain a clear security contact and disclosure procedure appropriate for the project stage.