Troubleshooting: Deployment

Common problems encountered while setting up a Global File System.

gfs-participant-add: Fails to Add a Site

Error:

gfs-participant-add: site 'SITE Q' not found.

The site cannot find the SITE Q identifier in the configuration exchanged between sites. Either the --site-name was misspelled (input is case-sensitive) or a shared object storage volume was not set up correctly between the sites.

gfs-participant-add: Site Is Already a Participant

Error:

gfs-participant-add: Site SITE B is already participant 1 of share Home.

The share is already replicating to that site. No action needed.

Error: Bad Credentials

Error:

gfs-participant-add: Unable to ascertain the software version running at 198.51.100.10. Cause: Remote site '198.51.100.10' returned error: bad credentials

The username or password supplied to gfs-participant-add was incorrect.

A Share with That Name Already Exists on the Remote Site

Error:

gfs-participant-add: Task failed.
ID:                      102f3726-f50c-4fa6-be6e-07e47117ed41
Name:                    gfs-participant-add
Status:                  FAILED
Status message:          Remote site '198.51.100.10' returned error: share 'Apps' already exists.
Created:                 2026-09-23 19:18:01 UTC
Started:                 2026-09-23 19:18:01 UTC
Ended:                   2026-09-23 19:18:02 UTC
Duration:                0s
Params:                  name: Apps::SITE B; created-by-name: admin; local-share-name: Apps; created-by: Uoid [uuid=4cf681ae-56bc-4d07-9832-c6d8feeaf475, objectType=USER]; local-share-internal-id: 2
Context:                 remote-participant-id: 2; remote-site: Site(internalId=1, name=SITE B, siteMgmtAddress=198.51.100.10, siteDataAddress=198.51.100.10, overrideMgmtAddress=null, overrideDataAddress=null, mgmtAddress=198.51.100.10, dataAddress=198.51.100.10, type=REMOTE)

The command reports Task failed. and prints the failed task; its Status message: line gives the cause. You cannot establish a replication relationship with an already-existing share on the remote site. Rename and move the share on the remote site, then retry. Share names are case-insensitive, so a different-case name on the remote site does not avoid this collision.

Replication Port-Check Failures

Symptom: participant-add fails, or participants flip to Suspected/Down, with a REPLICATION_PORT_CHECK_FAILED event. Confirm that all four Anvil ports (443, 9097, 9298, 9299) are open end-to-end between every pair of sites, and that the DME replication REST service is running. See Prerequisites, Sizing, and Networking.