open source is social v-it.org
docs(start): tighten login troubleshooting bullets for real user failure modes
Replace the generic five-bullet list with four Alex-oriented bullets
covering the concrete failure modes we actually see: Bluesky's "data is
invalid" page (browser session conflict), "Failed to resolve identity"
(DoH blocked, fall back to --app-password), CLI hang on a remote
machine (--remote), and DID-vs-handle guidance. Point to verbose mode
for cause chains.
+7
-7
+7
-7
docs/start/index.html
+7
-7
docs/start/index.html
···
396
396
397
397
<hr>
398
398
399
-
<h3>login troubleshooting</h3>
400
-
<p>if <code>vit login</code> fails, these are the usual fixes:</p>
399
+
<h3>if login gets stuck</h3>
400
+
<p>these are the four most common ways <code>vit login</code> fails, and what to do about them:</p>
401
401
<ul>
402
-
<li>make sure the handle is correct and resolves on Bluesky.</li>
403
-
<li>open the printed URL in your browser, approve vit, and wait for the callback to finish.</li>
404
-
<li>if you're on a remote machine, rerun with <code>vit login <handle> --remote</code> and paste the full callback URL.</li>
405
-
<li>if you used an app password, create a fresh Bluesky app password and try again.</li>
406
-
<li>check your DNS, firewall, or VPN settings if vit cannot reach Bluesky.</li>
402
+
<li><strong>“The data you submitted is invalid” on Bluesky’s page.</strong> you’re probably already signed in as a different bsky account in that browser. sign out of bsky (or open an incognito window) and retry.</li>
403
+
<li><strong>“Failed to resolve identity” on the CLI.</strong> your handle lookup is being blocked — often by a corporate network or VPN that blocks DNS-over-HTTPS. as a fallback, create a Bluesky app password at <a href="https://bsky.app/settings/app-passwords">bsky.app/settings/app-passwords</a> and run <code>vit login <handle> --app-password <password></code>.</li>
404
+
<li><strong>the CLI hangs after printing a URL.</strong> you’re on a remote or SSH machine without a browser. rerun with <code>--remote</code> and paste the callback URL back by hand.</li>
405
+
<li><strong>use your handle, not your DID.</strong> pass <code>alice.bsky.social</code>, not <code>did:plc:…</code>. the OAuth flow works much better with handles.</li>
407
406
</ul>
407
+
<p>for any login failure, <code>-v</code>/<code>--verbose</code> prints the full cause chain and stack traces.</p>
408
408
<span class="cmd-label">you run this (terminal, on a remote machine)</span>
409
409
<pre><code>vit login your-handle.bsky.social --remote</code></pre>
410
410