Troubleshooting 🛠️

Troubleshooting 🛠️#

Note

If you encounter any technical difficulties or have inquiries related to using Tidy3D, kindly submit a Customer Technical Support form, available on the right side of the Tidy3D Technical Support page. To ensure efficient assistance, please provide a thorough description of the issue or question, along with relevant screenshots or a link to a Loom recording.

As a token of our appreciation, for well-documented and confirmed bug reports, we will reward you with up to 50 FlexCredits.

Running tidy3d troubleshoot report (documented below) is the quickest way to attach a thorough, paste-ready description of your environment and connectivity state to the form.

When something is wrong with your Tidy3D setup — a simulation hangs, an upload fails, or authentication misbehaves — the fastest path to a fix is to run tidy3d troubleshoot and share the printed report with support. The command group collects platform, package, configuration, and connectivity information without exposing your API key.

Quick Start#

tidy3d troubleshoot report

Prompts for a short description, when it started, reproducibility, run mode, and script location, then probes your environment and Tidy3D connectivity and prints a bundle matching the issue-report template. Add --output report.md (or -o report.md) to write it to a file instead of stdout.

Subcommands#

Command

Purpose

troubleshoot report

Full bundle: prompts + environment + configuration + connectivity.

troubleshoot environment

Offline snapshot: Python, platform, Flexcompute packages, pip freeze, and the redacted client configuration.

troubleshoot connection

Network probe only: DNS, TCP, TLS, API latency, auth, 100 MiB download.

Options#

Common to every subcommand:

Option

Effect

--output PATH / -o PATH

Write the report to PATH instead of stdout (atomic replace).

--json

Emit structured JSON instead of the text summary.

--verbose

Print each phase’s individual probes to stderr before it runs.

--private-network-details

Include proxy hosts, NO_PROXY, certificate paths, resolved IPs, and TLS certificate metadata. Marks the report privacy_mode: private; share only with your IT administrators.

troubleshoot report extras:

Option

Effect

--task-id ID

Populates question 5 of the template.

--no-connection

Skip live network probes.

--traceback-file PATH

Inline the file contents into question 6 (steps to reproduce).

--non-interactive

Skip narrative prompts (for scripts / CI).

--api-samples N / --timeout SECONDS

Latency-sample count (default 3) and per-request timeout (default 20s).

Report Layout#

  1. Issue template — the seven questions, filled from your answers plus the auto-detected Tidy3D version and task ID.

  2. Environment — Python, platform, Flexcompute distributions (tidy3d, tidy3d-extras, flex-rf, photonforge, flow360), and a full pip freeze.

  3. Configuration — redacted API endpoint, SSL settings, proxy / certificate / Tidy3D env vars.

  4. Connection diagnostics — DNS, TCP + TLS, API latency, auth, and storage-download throughput, each with pass/fail and (where relevant) a recommended next step.

Privacy#

Default output is privacy_mode: shareable and safe to send to support: API keys, signed URL secrets, and proxy hosts are redacted or presence-only. --private-network-details switches to privacy_mode: private and embeds internal network details for IT — do not share it externally.

From Python#

The CLI is a thin wrapper over three helpers. Each returns a Pydantic model with support_text() and model_dump_json().

from tidy3d import web

print(web.diagnose_environment().support_text())
print(web.diagnose_connection().support_text())
print(web.diagnose_report(task_id="fdve-01H8ABCDEXAMPLE").support_text())