From b32a1e9ce81ce9fda4a1af3b060c2fb2e78d75cc Mon Sep 17 00:00:00 2001
From: Christian Byrne <cbyrne@comfy.org>
Date: Wed, 29 Oct 2025 19:31:56 -0700
Subject: [PATCH] [feat] add troubleshooting details to auth timeout view
 (#6380)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
- Enhances authentication timeout error page with actionable
troubleshooting information
- Adds collapsible technical error details for debugging
- Shows common causes: firewall blocks, VPN restrictions, browser
extensions, regional limitations
- Disables incompatible tailwindcss eslint plugin (Tailwind v4
compatibility issue)

## Changes
- Updated `CloudAuthTimeoutView.vue` with troubleshooting section and
collapsible technical details
- Pass error message from router to timeout view via route params
- Added i18n strings for new troubleshooting content
- Removed `eslint-plugin-tailwindcss` (incompatible with Tailwind
v4.1.12)
- Cleaned up unused knip entries

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-6380-feat-add-troubleshooting-details-to-auth-timeout-view-29b6d73d365081fea4e3d46b804d3116)
by [Unito](https://www.unito.io)
---
 eslint.config.ts                              | 16 ++---
 src/locales/en/main.json                      | 13 +++-
 src/onboardingCloudRoutes.ts                  |  3 +-
 .../onboarding/cloud/CloudAuthTimeoutView.vue | 70 +++++++++++++++++--
 src/router.ts                                 |  9 ++-
 5 files changed, 95 insertions(+), 16 deletions(-)

diff --git a/eslint.config.ts b/eslint.config.ts
index 2a4d219a9..3adb1b51e 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -5,7 +5,7 @@ import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescrip
 import { importX } from 'eslint-plugin-import-x'
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
 import storybook from 'eslint-plugin-storybook'
-import tailwind from 'eslint-plugin-tailwindcss'
+// import tailwind from 'eslint-plugin-tailwindcss'
 import unusedImports from 'eslint-plugin-unused-imports'
 import pluginVue from 'eslint-plugin-vue'
 import { defineConfig } from 'eslint/config'
@@ -34,11 +34,11 @@ const settings = {
       ],
       noWarnOnMultipleProjects: true
     })
-  ],
-  tailwindcss: {
-    config: `${import.meta.dirname}/packages/design-system/src/css/style.css`,
-    functions: ['cn', 'clsx', 'tw']
-  }
+  ]
+  // tailwindcss: {
+  //   config: `${import.meta.dirname}/packages/design-system/src/css/style.css`,
+  //   functions: ['cn', 'clsx', 'tw']
+  // }
 } as const
 
 const commonParserOptions = {
@@ -97,7 +97,7 @@ export default defineConfig([
   // Difference in typecheck on CI vs Local
   // eslint-disable-next-line @typescript-eslint/ban-ts-comment
   // @ts-ignore Bad types in the plugin
-  tailwind.configs['flat/recommended'],
+  // tailwind.configs['flat/recommended'],
   pluginVue.configs['flat/recommended'],
   eslintPluginPrettierRecommended,
   storybook.configs['flat/recommended'],
@@ -129,7 +129,7 @@ export default defineConfig([
       'import-x/no-relative-packages': 'error',
       'unused-imports/no-unused-imports': 'error',
       'no-console': ['error', { allow: ['warn', 'error'] }],
-      'tailwindcss/no-custom-classname': 'off', // TODO: fix
+      // 'tailwindcss/no-custom-classname': 'off', // TODO: fix
       'vue/no-v-html': 'off',
       // Enforce dark-theme: instead of dark: prefix
       'vue/no-restricted-class': ['error', '/^dark:/'],
diff --git a/src/locales/en/main.json b/src/locales/en/main.json
index 35e98b7ae..54bdc97a5 100644
--- a/src/locales/en/main.json
+++ b/src/locales/en/main.json
@@ -2114,7 +2114,18 @@
     "authTimeout": {
       "title": "Connection Taking Too Long",
       "message": "We're having trouble connecting to ComfyUI Cloud. This could be due to a slow connection or temporary service issue.",
-      "restart": "Sign Out & Try Again"
+      "restart": "Sign Out & Try Again",
+      "troubleshooting": "Common causes:",
+      "causes": [
+        "Corporate firewall or proxy blocking authentication services",
+        "VPN or network restrictions",
+        "Browser extensions interfering with requests",
+        "Regional network limitations",
+        "Try a different browser or network"
+      ],
+      "technicalDetails": "Technical Details",
+      "helpText": "Need help? Contact",
+      "supportLink": "support"
     }
   },
   "cloudFooter_needHelp": "Need Help?",
diff --git a/src/onboardingCloudRoutes.ts b/src/onboardingCloudRoutes.ts
index 4585ab8c9..2049027db 100644
--- a/src/onboardingCloudRoutes.ts
+++ b/src/onboardingCloudRoutes.ts
@@ -83,7 +83,8 @@ export const cloudOnboardingRoutes: RouteRecordRaw[] = [
         path: 'auth-timeout',
         name: 'cloud-auth-timeout',
         component: () =>
-          import('@/platform/onboarding/cloud/CloudAuthTimeoutView.vue')
+          import('@/platform/onboarding/cloud/CloudAuthTimeoutView.vue'),
+        props: true
       }
     ]
   }
diff --git a/src/platform/onboarding/cloud/CloudAuthTimeoutView.vue b/src/platform/onboarding/cloud/CloudAuthTimeoutView.vue
index 392e495ae..dc317064b 100644
--- a/src/platform/onboarding/cloud/CloudAuthTimeoutView.vue
+++ b/src/platform/onboarding/cloud/CloudAuthTimeoutView.vue
@@ -1,13 +1,67 @@
 <template>
-  <div class="flex h-full items-center justify-center p-8">
-    <div class="max-w-[100vw] text-center lg:w-96">
-      <h2 class="mb-4 text-xl">
+  <div class="flex h-full items-center justify-center p-6">
+    <div class="max-w-[100vw] text-center lg:w-[500px]">
+      <h2 class="mb-3 text-xl text-text-primary">
         {{ $t('cloudOnboarding.authTimeout.title') }}
       </h2>
-      <p class="mb-6 text-gray-600">
+      <p class="mb-5 text-muted">
         {{ $t('cloudOnboarding.authTimeout.message') }}
       </p>
 
+      <!-- Troubleshooting Section -->
+      <div
+        class="mb-4 rounded bg-surface-700 px-3 py-2 text-left dark-theme:bg-surface-800"
+      >
+        <h3 class="mb-2 text-sm font-semibold text-text-primary">
+          {{ $t('cloudOnboarding.authTimeout.troubleshooting') }}
+        </h3>
+        <ul class="space-y-1.5 text-sm text-muted">
+          <li
+            v-for="(cause, index) in $tm('cloudOnboarding.authTimeout.causes')"
+            :key="index"
+            class="flex gap-2"
+          >
+            <span>•</span>
+            <span>{{ cause }}</span>
+          </li>
+        </ul>
+      </div>
+
+      <!-- Technical Details (Collapsible) -->
+      <div v-if="errorMessage" class="mb-4 text-left">
+        <button
+          class="flex w-full items-center justify-between rounded bg-surface-600 px-4 py-2 text-sm text-muted transition-colors hover:bg-surface-500 dark-theme:bg-surface-700 dark-theme:hover:bg-surface-600"
+          @click="showTechnicalDetails = !showTechnicalDetails"
+        >
+          <span>{{ $t('cloudOnboarding.authTimeout.technicalDetails') }}</span>
+          <i
+            :class="[
+              'pi',
+              showTechnicalDetails ? 'pi-chevron-up' : 'pi-chevron-down'
+            ]"
+          ></i>
+        </button>
+        <div
+          v-if="showTechnicalDetails"
+          class="mt-2 rounded bg-surface-800 p-4 font-mono text-xs text-muted break-all dark-theme:bg-surface-900"
+        >
+          {{ errorMessage }}
+        </div>
+      </div>
+
+      <!-- Helpful Links -->
+      <p class="mb-5 text-center text-sm text-gray-600">
+        {{ $t('cloudOnboarding.authTimeout.helpText') }}
+        <a
+          href="https://support.comfy.org"
+          class="cursor-pointer text-blue-400 no-underline"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          {{ $t('cloudOnboarding.authTimeout.supportLink') }}</a
+        >.
+      </p>
+
       <div class="flex flex-col gap-3">
         <Button
           :label="$t('cloudOnboarding.authTimeout.restart')"
@@ -21,12 +75,20 @@
 
 <script setup lang="ts">
 import Button from 'primevue/button'
+import { ref } from 'vue'
 import { useRouter } from 'vue-router'
 
 import { useFirebaseAuthActions } from '@/composables/auth/useFirebaseAuthActions'
 
+interface Props {
+  errorMessage?: string
+}
+
+defineProps<Props>()
+
 const router = useRouter()
 const { logout } = useFirebaseAuthActions()
+const showTechnicalDetails = ref(false)
 
 const handleRestart = async () => {
   await logout()
diff --git a/src/router.ts b/src/router.ts
index e39d7cd00..41c63a7fd 100644
--- a/src/router.ts
+++ b/src/router.ts
@@ -129,8 +129,13 @@ router.beforeEach(async (to, _from, next) => {
       })
     } catch (error) {
       console.error('Auth initialization failed:', error)
-      // Navigate to auth timeout recovery page
-      return next({ name: 'cloud-auth-timeout' })
+      // Navigate to auth timeout recovery page with error details
+      return next({
+        name: 'cloud-auth-timeout',
+        params: {
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      })
     }
   }