Limitations and Troubleshooting

Known Limitations and Constraints

These should be communicated clearly to stakeholders to set proper expectations.

Anonymous Access Only

PTC currently operates with anonymous access. Redirected requests from Zscaler arrive at Artifactory without authentication credentials.

Impact:

• Only public packages from public registries can be redirected and served
• Private/scoped packages requiring authentication (e.g., @company/private-package on npm) are not supported as anonymous redirect traffic
• Audit trails will show anonymous requests rather than identified users
• Per-user download tracking is not available in this release

Workarounds:

• Direct client access: Configure the package manager to reach Artifactory (or the upstream registry) with credentials, bypassing the anonymous redirect hop.
• Artifactory-side credentials: A remote repository under the virtual that authenticates to the upstream may allow gated public-registry content to resolve; this pattern is not fully regression-tested for all ecosystems—see the Overview and your account team before relying on it in production. Hugging Face gated models are called out explicitly under Hugging Face models and registry limitations.

npm login (Web Login) Fails

npm publish works because PUT requests are not redirected. For users who need to log in and publish packages to the public npm registry (not Artifactory), default npm login (web login) fails because Zscaler intercepts a GET call in the login flow (/v1/done callback) and redirects it to Artifactory.

Workarounds:

• Option 1: Add a token directly in .npmrc using npm config set (local config only) — works
• Option 2: Use legacy login: npm login --auth-type legacy — works
• Avoid: Default npm login (web login) — fails

POST-Based Commands Not Redirected

Commands that use HTTP POST are explicitly excluded from the redirect rules to prevent failures. npm is documented in detail in Configuration by package type; other clients (including Python tooling) may use POST to registry hosts—confirm with Zscaler logs and keep non-GET methods off the redirect rule unless you have tested them.

Implication: These commands are not covered by Curation policies and will not appear in the Artifactory audit trail.

CI/CD Consistency

PTC governs traffic from workstations where Zscaler Client Connector is running. CI/CD systems may use a different network path, which means package resolution in CI could differ from developer workstations if not explicitly configured.

To ensure consistent resolution across both environments, use one of the following approaches:

• Route CI through PTC: If your CI runners are behind Zscaler, they will be governed by the same redirect rules as developer workstations automatically.
• Configure CI clients directly: If CI runners are not behind Zscaler, point package manager clients explicitly at Artifactory using client configuration (e.g. .npmrc, pip.conf, UV_INDEX_URL). This ensures lock files and resolved artifacts stay consistent with what developers get through PTC.

Either approach produces a consistent, Artifactory-backed resolution path. The choice depends on your CI network topology.

Hugging Face models and registry limitations

Gated or licensed models (artifacts that require authentication to Hugging Face) do not work through a pure anonymous redirect the same way as fully public files. The Zscaler → Artifactory redirect path does not carry the developer’s Hugging Face token. Mitigation: Configure an Artifactory remote repository (or equivalent) that stores Hugging Face credentials, and resolve those assets through your virtual repository. Follow JFrog’s Hugging Face integration documentation for repository layout and authentication.

Xet transfer protocol is not supported: Hugging Face's Xet storage protocol is not supported through the PTC redirect flow. To use PTC with Hugging Face, Xet must be disabled on the workstation by setting the environment variable:

HF_HUB_DISABLE_XET=1

Important: Disabling Xet is a workstation-wide setting — it affects all Hugging Face downloads from that machine, not only those routed through PTC. Downloads will fall back to standard HTTPS transfers, which may be slower for large model files.
If the workstation is later reconfigured to work directly with Artifactory (pointing the Hugging Face client at Artifactory's Hugging Face repository URL with credentials, rather than relying on the PTC anonymous redirect), remove the Xet disable setting so that Xet transfers resume for direct Artifactory use.
Large assets and transfer semantics: Hugging Face content is often large. With Xet disabled, downloads use standard HTTPS, which may differ in performance from the native Hugging Face CLI or hub client. Confirm performance and semantics with your JFrog account team for your release.

Certificate distribution (MDM optional)

MDM is not mandatory. Many teams use an MDM (Microsoft Intune, Jamf, etc.) or similar endpoint platform to push the Zscaler CA and environment variables at scale, but you may use any reliable method: configuration management, golden images, login scripts, or guided manual installation (common in labs and pilots). Ad hoc manual steps are easy to get wrong across many machines—automate when you can, and follow Zscaler’s guidance. For npm and application trust stores, see Adding Custom Certificate to an Application-Specific Trust Store.

Python 3.13+ with Older Zscaler Certificates

Python 3.13 introduced stricter TLS certificate validation. Organizations still running pre-mid-2024 Zscaler root CA certificates will experience TLS failures with Python tools that rely on the Python ssl module (Poetry), while tools that bypass it (pip ≥ 24.2 via truststore, uv via Rust TLS) continue to work. Upgrade your Zscaler certificate to the versions released mid-2024 or later to resolve the issue. See Python 3.13+ and Zscaler Certificate Compatibility for the full compatibility matrix and workarounds.

Older Package Manager Versions

Troubleshooting and Rollback

Verifying the Setup

Client-Side Checks

Run these checks from a developer workstation with ZCC active.

1. Verify ZCC Is Running

• macOS: ZCC icon in the menu bar should show a connected state.
• Windows: ZCC icon in the system tray should show a connected state.
• Linux: Confirm the Zscaler client your org uses on Linux is running and connected (exact check depends on install—e.g. service status or CLI your IT documents); there is no single universal UI.

2. Verify SSL Inspection Is Active

openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org 2>/dev/null | openssl x509 -noout -issuer

Where:

• registry.npmjs.org: Example public npm registry hostname (use the host you intercept for other ecosystems)

If SSL inspection is active, the issuer should be the Zscaler CA, not the original registry's CA.

Verify NODE_EXTRA_CA_CERTS points at your Zscaler CA bundle:

openssl x509 -in "$NODE_EXTRA_CA_CERTS" -noout -issuer

Expected (example): issuer=C=US, ST=California, L=San Jose, O=Zscaler Inc., OU=Zscaler Inc., CN=Zscaler Root CA, [email protected]

Check That the Redirect Is Working

3. Verify Redirect Is Working

curl -v -L "https://registry.npmjs.org/express" 2>&1 | grep -i "location"

You should see a Location header pointing to your Artifactory instance.

4. Verify Package Install Works

# Test end-to-end (--loglevel verbose shows GETs so you can confirm traffic hits Artifactory)
npm install express --loglevel verbose
# Example: look for GET 200 https://<YOUR_ARTIFACTORY_URL>/artifactory/api/npm/npm-virtual/express

The command should complete successfully with the package resolved through Artifactory.

Server-Side Checks

1. Verify redirect endpoint — Use the full curl test, encoding rules, and expected 302/307 behavior in Step 6: Verify the Redirect Endpoint only (Router /package-reroute, not /artifactory/api/package-reroute/...).

2. Verify Packages Are Cached

Open Artifactory > Artifacts, navigate to the remote repository, and confirm the package appears.

3. Verify Curation Audit Log (if Curation is enabled)

Navigate to Curation > Audit and confirm recent entries with package name, policy decision, and timestamp. If Curation is not in use, omit this check.

Common Issues and Solutions

Issue: Package Install Fails with SSL Error

• Symptom: SSL certificate problem or UNABLE_TO_GET_ISSUER_CERT_LOCALLY
• Cause: The Zscaler CA certificate is not trusted by the OS.
• NODE_EXTRA_CA_CERTS is not set or points to the wrong file. Verify with: openssl x509 -in "$NODE_EXTRA_CA_CERTS" -noout -issuer (should show Zscaler Root CA).
• Long-term fix: Distribute the certificate and environment variables through your standard workstation process (MDM, endpoint tooling, or another repeatable method).

Issue: Package Install Fails with 403 Forbidden

• Symptom: HTTP 403 error from Artifactory.
• Cause: Anonymous access is not enabled.
• Solution: Navigate to Administration > Security > Settings, enable Allow Anonymous Access, and ensure anonymous users have read and deploy permissions on the remote repositories.

Issue: npm audit Fails

• Symptom: npm audit returns an error or unexpected redirect response.
• Cause: POST requests are being redirected.
• Solution: Verify that the URL Filtering rule only includes GET and HEAD request methods.

Issue: Package Install Succeeds but Package Not Visible in Artifactory

• Symptom: npm install succeeds, but the package does not appear in Artifactory.
• Cause: The package was served from the local npm cache.
• Solution: npm cache clean --force && npm install <package>

Issue: Redirect Not Working (Traffic Goes Directly to Public Registry)

• Possible causes:
  1. ZCC not running on the workstation
  2. SSL Inspection rule not above default bypass rules
  3. URL category mismatch (e.g., registry.npmjs.org vs npmjs.org)
  4. User not in the target group (scoped deployment)
  5. Policy not activated after configuration

Rollback Process

If PTC needs to be reverted, follow Rollback Process.

To perform a quick rollback (stop redirects only):

Stop redirecting by removing every registry hostname you added for PTC from the custom URL category (e.g. JFrog_Target_Registries)—across all ecosystems you enabled (see the reference hostnames list for typical examples)—or disable the URL Filtering redirect rule that targets that category. Activate the policy change in ZIA. You typically do not need to change Artifactory for this quick path (see the note at the end of this section).

To perform a full ZIA rollback:

1. Navigate to Policy > URL & Cloud App Control > URL Filtering Policy in ZIA.

2. Find the redirect rule (for example Redirect_Registries_to_Artifactory).

3. Disable or delete the rule.

4. Click Activate Change.

5. Navigate to Policy > SSL Inspection in ZIA.

6. Find the inspection rule (for example Inspect_JFrog_Registries).

7. Disable or delete the rule.

8. Click Activate Change.

9. (Optional) Navigate to Administration > URL Categories in ZIA, find JFrog_Target_Registries, and delete the category (only after removing all rules that reference it).

To verify rollback on a workstation:

# Should show the original registry CA, not Zscaler CA
openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org 2>/dev/null | openssl x509 -noout -issuer

# Package install should work directly against public registry (optional: --loglevel verbose to inspect GET targets)
npm install express --loglevel verbose

Note on Artifactory Configuration: The JFrog Artifactory configuration (repositories, Curation policies, anonymous access) does not need to be rolled back. These settings can remain in place without affecting developers once the Zscaler redirect is disabled.

Frequently Asked Questions

This section provides answers to frequently asked questions about PTC limitations and troubleshooting.

Related Topics

• Package Traffic Controller (PTC) overview
• Configuration by Package Type
• Configure Artifactory for PTC