Troubleshooting and reference
Every message the hosting pages can show you, what it means, and what to do next. Messages are quoted exactly as the product shows them, so you can search this page for the text you see.
Creating the server
| You see | Why | Do this |
|---|---|---|
| Must start with a letter and cannot contain spaces or underscores (_). | The Perforce URL label becomes part of a hostname. | Use letters, digits and hyphens, starting with a letter. p4 is a good default. |
| 1 / 1 hosting servers | The project already has its one Perforce server, so Add is disabled. | Use the existing server. To replace it, ask support to retire it first. |
| Your Perforce server is being created. Waiting for project source control to finish provisioning. | Normal. Provisioning is running. | Wait. Usually a few minutes. You can leave the page. |
| Provisioning timed out | The page stopped waiting after about three minutes, but provisioning continues in the background. | Reload the page after a short wait. If nothing has changed after thirty minutes, email [email protected]. |
| Perforce service was created but project source control is not ready yet. Please refresh the page. | The server exists; the page has not yet received its details. | Refresh the page. |
| Almost there | A migration finished but the server details are still publishing. | Refresh in a moment. |
No email? Check the project maintainer's spam folder. The password cannot be shown again; if the email is lost, [email protected] will reset it.
Connecting
| You see | Why | Do this |
|---|---|---|
| The fingerprint shown by p4 trust does not match the connection card | You are connecting to a different host, or something is intercepting the connection. | Stop. Check the address you typed against the card. If it matches and the fingerprint still differs, email [email protected]. Without a p4 client you can read the server's fingerprint with OpenSSL: openssl s_client -connect HOST:PORT </dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform DER | openssl dgst -sha1 -c |
| Connection refused, or a plaintext connection error | The address is missing the ssl: prefix. Hosted servers have no plaintext port. | Use ssl:p4.starfall.northwind.example.com:1666. |
| Perforce asks you to change your password on first login | dsl_admin is required to replace the emailed password. | Run p4 passwd, then p4 login again. |
| The new password is rejected as too weak | The server runs at security level 4. | Use at least eight characters with a mix of character classes. |
| Swarm keeps returning you to its login page | Swarm requires sign-in and uses Perforce accounts. | Sign in with the same username and password you use for p4. |
Migration: the rsync command is refused
The intake checks your command before anything runs and shows one of these reasons next to the field. Nothing you type is ever passed to a shell; the command is parsed into a fixed shape and rebuilt.
| You see | Why | Do this |
|---|---|---|
| the command must invoke rsync (got '…') | The command did not start with rsync. | Start with rsync. |
| password authentication (sshpass) is not supported; authorize the provided SSH public key on your server instead | Only the key we issued is used to connect. | Remove sshpass or any password option and install our key line as in the handshake. |
| the only accepted form is -e 'ssh -p <port>' to pick a port | SSH options other than the port are ours to set (identity, known hosts, batch mode). | Use exactly -e 'ssh -p 2222', or drop -e for port 22. |
| ssh port <n> is out of range | The port must be 1–65535. | Correct the port number. |
| options that read or write paths on our server are not permitted | --files-from, --include-from, --exclude-from, --log-file, --temp-dir, --partial-dir, --backup-dir, --compare-dest, --copy-dest and --link-dest name paths on the destination. | Remove the option. Use inline --exclude=PATTERN if you need to exclude files. |
| the transfer must never modify your source server | --remove-source-files would delete from your server. | Remove it. |
| overriding the remote rsync binary is not supported | --rsync-path is refused. | Remove it. |
| rsync daemon mode is not supported | --daemon, --config and --dparam are for rsync servers, not transfers. | Remove them. |
| batch mode is not supported | Batch files cannot be produced or consumed in a managed transfer. | Remove the --write-batch / --read-batch options. |
| destination must be $DSL_P4ROOT/ (got '…') | We substitute the new server's P4ROOT; the destination is fixed. | End the command with "$DSL_P4ROOT"/, including the quotes and the slash. |
| source must be user@host:/absolute/path/to/p4root/ | The source must name a user, a host and an absolute path. | For example perforce@p4.oldstudio.example.com:/opt/perforce/p4root/. |
| source path must end with '/' so the p4root CONTENTS are copied (content-to-content), not nested under a directory -- use '…/' | Without the trailing slash, rsync would create a p4root directory inside the new P4ROOT. | Add the trailing slash to the source path. |
| source path '…' must be absolute and may only contain letters, digits, and . _ / @ + - (no spaces) | Relative paths and unusual characters are refused. | Use the absolute path to your P4ROOT or backup directory. |
| source path must not contain '..' segments | Parent-directory segments are refused. | Write the path without .. |
| <option>: option is not supported in managed transfers | An rsync option outside the accepted set. | Keep to -a, -z, --exclude, --bwlimit and the port form of -e. |
| You see | Why | Do this |
|---|---|---|
| finalize requires a completed transfer (migration is <state>); stop your source server, run one more sync, then finalize | Finalize is only available once a sync has completed. | Choose Start transfer or Re-sync changes, wait for Your data is copied, then finalize. |
| the rsync command cannot be changed while the migration is <state> | The command is locked while a transfer runs or once the migration is finalizing. | Wait for the transfer to finish, or choose Cancel transfer first. |
| no validated rsync command has been submitted yet | Start transfer was requested before a command was accepted. | Enter the command and choose Check command first. |
Migration: the transfer fails
When a transfer stops, The transfer did not finish shows the error exactly as the transfer reported it. These are the common ones.
| You see | Why | Do this |
|---|---|---|
| ssh: connect to host p4.oldstudio.example.com port 22: Connection timed out | Your firewall is not letting our transfer address in, or the host or port is wrong. | Allow inbound SSH from the address shown in the checklist (203.0.113.20 in this guide) and check the host and port in your command. |
| Permission denied (publickey). | The key line is not installed for the user in your command, or the command names a different user. | Re-check the handshake: the key line must be in that exact user's ~/.ssh/authorized_keys, with permissions 600. |
| rsync: change_dir … failed: Permission denied | The user cannot read your P4ROOT. | Grant that user read access to the whole directory tree, or use a user that has it. |
| Host key verification failed | Your server's SSH host key changed since our first contact. We refuse rather than continue silently. | Compare the Your server's host key card with your server. If the change is expected, email [email protected] to re-pin it. |
| Stalled — retrying | No progress for a while; usually the network. | Wait. The transfer resumes on its own and retries up to five times before it is marked failed. |
| some files vanished before they could be transferred | Your server is live and files changed during the copy. Expected. | Nothing. A later sync picks them up; the final delta at finalize catches everything. |
Build on check-in
| You see | Why | Do this |
|---|---|---|
| this project has no Build Stream service to send check-ins to; create one first | Check-ins need a Build Stream service on the project to be sent to. | Follow Add Build Stream to this project, then turn the switch on again. |
| the project's Build Stream service does not have a URL yet; try again once it is ready | Build Stream is still provisioning. | Wait a few minutes and try again. |
| build triggers are configured on the primary Perforce server, not the standby | An internal condition you should not see. | Email [email protected]. |
| Pushes are arriving on branches that are not set up to build | Submits are reaching Build Stream, but the path is not mapped to a branch with a build configuration. | Good news: delivery works. Get the depot path mapped; see Map a depot path to a branch. |
| The switch is on but nothing builds and no notice appears | Either the switch is still applying, or the submit touched no mapped path. | Work through Turned on, but nothing builds. |
Backup & export
| You see | Why | Do this |
|---|---|---|
| no SSH public key supplied | The key field is empty. | Paste the single line from perforce-backup-key.pub. |
| supply a single public key line (no newlines) | More than one line was pasted, or a private key. | Paste only the one-line public key. |
| malformed public key: expected '<type> <base64> [comment]' | The line is not in OpenSSH public-key format. | Copy the .pub file's contents exactly. |
| unsupported key type 'ssh-dss'; use one of ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, ssh-rsa | DSA keys are not accepted. | Generate an Ed25519 key: ssh-keygen -t ed25519. |
| malformed public key: the key body is not valid base64 | The key body was altered, often by a line wrap. | Re-copy the key as one line. |
| no backup server IP supplied | The address field is empty. | Enter your backup machine's public address. |
| '…' is not a valid IP address or CIDR | The address did not parse. | Use dotted notation, for example 198.51.100.7 or 198.51.100.0/28. |
| the backup IP must not be an all-addresses range (/0) | The endpoint must be locked to a real source. | Enter your backup machine's address or a narrow range. |
| Permission denied (publickey) on the first pull | The endpoint showed Enabled a moment before the key landed on it, or the pasted key was not the complete .pub line. | Wait a minute and retry. If it persists, use Change access and paste the whole line from perforce-backup-key.pub again: the form accepts any base64 body, so a truncated key is only caught when you connect. |
| Setting up your backup endpoint… for a long time | Allocation or arming is slow, or failed. | Wait a few minutes. If a reason appears on the panel, correct it and choose Try again. |
| Connection refused / timed out (from your backup machine) | You are not connecting from the whitelisted address, or the port is wrong. | Check Whitelisted from and Endpoint on the panel against your machine's public address and the port in your command. |
| Permission denied (publickey). (from your backup machine) | The -i path is wrong, or a different key than the one you pasted. | Point -i at the private half of the key you pasted. |
| this endpoint is read-only; only 'rsync --sender' (a pull) is allowed | The command was changed into a push or a non-rsync command. | Use the command from the panel, editing only the two placeholders. |
| The restored server says it is unlicensed | Licenses are never exported. | Install your license file into the restored P4ROOT. See Licensing. |
Frequently asked questions
Can I switch a server from Start fresh to Bring my server across?
No. The starting point is chosen when the server is created and cannot be changed. To migrate data into a project whose server was created empty, ask support to retire the server and create it again in migration mode.
Where is my dsl_admin password?
It was emailed once to the project maintainer, in the message titled Perforce is ready for <project name> (the project's display name, Starfall in this guide). It is never shown in the app or the API. If the email is lost, email support with the project name and we will reset it.
Can a project have two Perforce servers?
No. One Perforce server per project. The hosting page shows the count as 0 / 1 or 1 / 1 hosting servers.
How do I delete a Perforce server?
There is no delete button. Retiring a server is done by our team so that a server holding your history cannot be removed by an accidental click. Email support with the project name; pull a backup first if you want a copy.
Is Swarm optional? Does it cost extra?
Swarm is provisioned with every server at no extra charge. You do not have to use it; it is simply available at the Swarm Server address on the connection card.
Do you back up my server, or do I have to?
Both are true. The platform keeps its own backups of your server. Backup & export additionally gives you your own restorable copy on a machine you control, whenever you want one.
Which ports do I need open?
Outbound from your clients and build machines: the server's TLS port, 1666. Inbound to a server you are migrating from: SSH from our transfer address only, and only for the duration of the migration. For exports: outbound from your backup machine to the endpoint port shown on the panel.
Can I connect without TLS?
No. Hosted servers accept ssl: connections only.
Does a migrated server keep my users and passwords?
Yes. Users and passwords come across with your data. dsl_admin is added as a super user alongside your existing protections.
How long does a migration take?
It depends on the size of your depot and your server's upload bandwidth; large depots can take hours for the first sync. Later syncs copy only what changed. Your server can stay live until you finalize.
How many users can I add?
Standard users occupy licensed seats. For the seat count on your server and how to add more, email support.
Reference
Addresses and ports
| What | Pattern | Example |
|---|---|---|
| Perforce server | ssl:<label>.<project>.<org>.…:1666 | ssl:p4.starfall.northwind.example.com:1666 |
| Swarm | https://<label>-swarm.<project>.<org>.… | https://p4-swarm.starfall.northwind.example.com |
| Migration, temporary | ssl:<label>.….:<public port> | ssl:p4.starfall.northwind.example.com:55123 |
| Our transfer address | Shown in the migration checklist | 203.0.113.20 |
| Export endpoint | Shown on the export panel | 203.0.113.20:42022 |
What an export contains
| Included | Excluded |
|---|---|
A consistent checkpoint, checkpoint.ckp.N.gz, cut at most once every 15 minutes | The live db.* files |
| The depot archive directories | The Perforce license file |
| Replica and standby state, the TLS private key, our credential files |
Limits
| Limit | Value |
|---|---|
| Perforce servers per project | 1 |
| Who can configure hosting, backups and check-in builds | Project administrators |
| Client connections | TLS only (ssl:) |
| Export source addresses | One IP address or CIDR range per endpoint |
| Automatic transfer retries during a migration | 5 |
The accounts on your server are listed on Accounts, security and licensing.
Getting help
Something out of date or unclear? Email [email protected].