Troubleshooting & Common Error Resolution

This runbook helps resolve common issues encountered while browsing Google Cloud Filestore instances via the NFS Browser skill.

1. Network & VPC Errors

Error: mount.nfs: Connection timed out

• Root Cause: VPC firewall rule is missing or blocking port 2049.

• Resolution: Ensure an ingress firewall rule permits TCP/UDP port 2049 between the client subnet (or Cloud Run Direct VPC Egress subnet) and the Filestore network:

  CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-nfs-browser)" \
  gcloud compute firewall-rules create allow-filestore-nfs \
    --network={vpc_network} \
    --allow=tcp:2049,udp:2049 \
    --source-ranges={client_subnet_cidr}
  

2. Authentication & IAM Errors

Error: HTTP 401 Unauthorized or HTTP 403 Forbidden on Bridge

• Root Cause: Caller lacks roles/run.invoker on the Cloud Run service or identity token is expired.

• Resolution:

  1. Grant the invoker role:

     gcloud run services add-iam-policy-binding filestore-nfs-bridge \
       --region={region} \
       --member="user:{user_email}" \
       --role="roles/run.invoker"
     

  2. Refresh the identity token:

     export FILESTORE_BRIDGE_TOKEN=$(gcloud auth print-identity-token)
     

3. Path & File Inspection Errors

Error: Path not found: /xyz

• Root Cause: Path specified is relative or does not exist on the NFS export.
• Resolution: Run tree with --path=/ and --depth=1 to explore the root directory structure first.

Error: Binary file detected. Raw content suppressed.

• Root Cause: Target file contains binary data (e.g. tarball, zip, ELF binary).
• Resolution: Use stat command to view file metadata, or use specific line slices if viewing text embedded in files.