diff --git a/src/content/docs/cloudflare-one/connections/connect-devices/warp/troubleshooting/troubleshooting-guide.mdx b/src/content/docs/cloudflare-one/connections/connect-devices/warp/troubleshooting/troubleshooting-guide.mdx
new file mode 100644
index 000000000000000..851ae53b5da8300
--- /dev/null
+++ b/src/content/docs/cloudflare-one/connections/connect-devices/warp/troubleshooting/troubleshooting-guide.mdx
@@ -0,0 +1,75 @@
+---
+pcx_content_type: reference
+title: WARP troubleshooting guide
+sidebar:
+  order: 0
+---
+
+This guide helps you diagnose and resolve common issues with the Cloudflare WARP client. It covers various aspects of WARP's functionality and provides steps for effective troubleshooting.
+
+## WARP architecture
+
+The WARP client consists of:
+
+content from https://github.com/cloudflare/cloudflare-docs/pull/23590
+
+The GUI and daemon (or service) have different names and are stored in the following locations:
+
+<details>
+<summary>Windows</summary>
+
+|                      | Windows                                                                                                                                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Service / Daemon** | `C:\Program Files\Cloudflare\Cloudflare WARP\warp-svc.exe`                                                                                                                                                       |
+| **GUI application**  | `C:\Program Files\Cloudflare\Cloudflare WARP\Cloudflare WARP.exe`                                                                                                                                                |
+| **Logs Location**    | <details><summary>Daemon</summary><br/>`C:\ProgramData\Cloudflare\`</details><br/><details><summary>GUI Logs</summary><br/>`C:\Users\<USER>.WARP\AppData\Local`<br/>or<br/>`%LOCALAPPDATA%\Cloudflare`</details> |
+
+</details>
+
+<details>
+<summary>macOS</summary>
+
+|                      | macOS                                                                                                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Service / Daemon** | `/Applications/Cloudflare WARP.app/Contents/Resources/CloudflareWARP`                                                                                                           |
+| **GUI application**  | `/Applications/Cloudflare WARP.app/Contents/MacOS/Cloudflare WARP`                                                                                                              |
+| **Logs Location**    | <details><summary>Daemon</summary><br/>`/Library/Application Support/Cloudflare/`</details><br/><details><summary>GUI Logs</summary><br/>`~/Library/Logs/Cloudflare/`</details> |
+
+</details>
+
+<details>
+<summary>Linux</summary>
+
+|                      | Linux                                                      |
+| -------------------- | ---------------------------------------------------------- |
+| **Service / Daemon** | `/bin/warp-svc`                                            |
+| **GUI application**  | `/bin/warp-taskbar`                                        |
+| **Logs Location**    | `/var/log/cloudflare-warp/`<br/>`/var/lib/cloudflare-warp` |
+
+</details>
+
+Along with the WARP GUI and daemon, `warp-cli` and `warp-diag` are also installed on the machine and added to the system path for use from any terminal session.
+
+[`warp-diag`](/cloudflare-one/connections/connect-devices/warp/troubleshooting/warp-logs/) is a command-line diagnostics tool that collects logs, configuration details, and connectivity data from the WARP client to help troubleshoot issues.
+
+`warp-cli` is the command-line interface (CLI) for managing and configuring the Cloudflare WARP client, allowing users to connect, disconnect, and adjust settings programmatically.
+
+:::tip
+
+Run `warp-cli help` and `warp-diag help` in your terminal to review the available subcommands and options.
+
+:::
+
+## WARP modes
+
+WARP operates in several modes, each with different traffic handling capabilities:
+
+content from https://github.com/cloudflare/cloudflare-docs/pull/23588
+
+:::tip
+
+Run `warp-cli settings` to review your device’s current WARP mode and other configured [WARP settings](/cloudflare-one/connections/connect-devices/warp/configure-warp/warp-settings/).
+
+:::
+
+## Troubleshooting steps