Limitations and Troubleshooting

Known Limitations and Constraints

Review these constraints before broad rollout.

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 and scoped packages requiring authentication (for example, @company/private-package on npm) are not supported as anonymous redirect traffic
• Audit logs can show anonymous requests unless your environment maps identity during redirect handling
• Per-user tracking depends on your Artifactory, identity, and network integration setup

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: Storing upstream credentials on the PTC remote repository can allow some gated public-registry content to resolve. Validate this pattern for your ecosystem before production use. Hugging Face gated models are called out explicitly under Hugging Face models and registry limitations.

npm Login Web Flow 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 JFrog 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 the Hugging Face remote repository (the one set as the PTC repo_key for huggingfaceml) with stored Hugging Face credentials so Artifactory can authenticate to the upstream on behalf of anonymous redirected requests. Follow JFrog’s Hugging Face integration documentation for repository configuration 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 with Optional MDM

MDM is not mandatory. You can use MDM, configuration management, imaging, login scripts, or guided manual installation. For scale and consistency, automate certificate and environment deployment where possible. For npm and application trust stores, see Adding Custom Certificate to an Application-Specific Trust Store.

Strict SSL Certificate Validation in Python Tools

Python-based package tools use Python's built-in ssl module for HTTPS connections, which requires certificates to be RFC 5280 compliant. If your SASE provider uses an older certificate that doesn't meet these requirements, some Python-based tools may encounter TLS errors. This is not tied to a specific Python version — it depends on the combination of the certificate in use and the OpenSSL version Python was compiled against. Tools that bypass the Python ssl module (pip ≥ 24.2 via truststore, uv via Rust TLS) continue to work. Ask your SASE provider administrator to update the CA certificate to an RFC 5280 compliant version — most providers have issued updated certificates since mid-2024. See Strict SSL Certificate Validation in Python Tools for the full compatibility matrix and resolution steps.

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 organization uses on Linux is running and connected (exact check depends on installation, for example 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-remote-registry/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 5: 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:
  Shell

  npm cache clean --force && npm install <PACKAGE_NAME>

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 (for example 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 Note on Artifactory Configuration).

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