Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart

Show why a server connection failed on the login screen

Barnabasbefc673d6335
diff --git a/lib/screens/login_screen.dart b/lib/screens/login_screen.dart
index c3003541..9639789e 100644
--- a/lib/screens/login_screen.dart
+++ b/lib/screens/login_screen.dart
@@ -44,6 +44,10 @@ class _LoginScreenState extends State<LoginScreen>
bool _serverValid = false;
bool _serverChecking = false;
String? _serverError;
+ // Technical reason the last check failed (TLS, timeout, HTTP status, etc.),
+ // shown beneath the field so unreachable-in-app-but-fine-in-browser servers
+ // are diagnosable instead of just "could not reach server".
+ String? _serverErrorDetail;
Timer? _debounce;
// Login error
@@ -127,6 +131,7 @@ class _LoginScreenState extends State<LoginScreen>
_serverValid = false;
_serverChecking = false;
_serverError = null;
+ _serverErrorDetail = null;
_lastValidatedServer = '';
});
_debounce?.cancel();
@@ -173,7 +178,8 @@ class _LoginScreenState extends State<LoginScreen>
try {
final headers = _collectHeaders();
- final ok = await ApiService.pingServer(fullUrl, customHeaders: headers);
+ final result = await ApiService.pingServerDetailed(fullUrl, customHeaders: headers);
+ final ok = result.ok;
if (!mounted) return;
if (_serverController.text.trim() != text) return;
@@ -181,6 +187,7 @@ class _LoginScreenState extends State<LoginScreen>
_serverChecking = false;
_serverValid = ok;
_serverError = ok ? null : AppLocalizations.of(context)!.loginCouldNotReachServer;
+ _serverErrorDetail = ok ? null : result.detail;
if (ok) {
_lastValidatedServer = fullUrl;
} else {
@@ -205,6 +212,7 @@ class _LoginScreenState extends State<LoginScreen>
_serverChecking = false;
_serverValid = false;
_serverError = AppLocalizations.of(context)!.loginCouldNotReachServer;
+ _serverErrorDetail = e.toString();
_oidcConfig = null;
});
}
@@ -533,6 +541,20 @@ class _LoginScreenState extends State<LoginScreen>
errorText: _serverError,
),
+ if (_serverErrorDetail != null) ...[
+ const SizedBox(height: 6),
+ Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 4),
+ child: Text(
+ _serverErrorDetail!,
+ style: TextStyle(
+ fontSize: 11,
+ color: cs.onSurfaceVariant.withValues(alpha: 0.6),
+ ),
+ ),
+ ),
+ ],
+
// Advanced: Custom Headers — must be before server validation
const SizedBox(height: 8),
GestureDetector(
diff --git a/lib/services/api_service.dart b/lib/services/api_service.dart
index 552254b2..311bee58 100644
--- a/lib/services/api_service.dart
+++ b/lib/services/api_service.dart
@@ -270,6 +270,57 @@ class ApiService {
}
}
+ /// Ping the server and report why it failed, for the login screen. The
+ /// plain [pingServer] collapses every failure into a single false, which
+ /// leaves users (and us) blind when a server reachable in a browser won't
+ /// connect in the app - usually a proxy/CDN treating the app's request
+ /// differently than a browser. Kept separate so the connectivity hot paths
+ /// keep their lean bool + short timeouts. [detail] is null on success.
+ static Future<({bool ok, String? detail})> pingServerDetailed(
+ String serverUrl, {
+ Map<String, String> customHeaders = const {},
+ }) async {
+ final url = serverUrl.endsWith('/') ? '${serverUrl}ping' : '$serverUrl/ping';
+ try {
+ final response = await http
+ .get(Uri.parse(url), headers: customHeaders.isNotEmpty ? customHeaders : null)
+ .timeout(const Duration(seconds: 15));
+ if (response.statusCode == 200) return (ok: true, detail: null);
+ return (ok: false, detail: 'Server returned HTTP ${response.statusCode} instead of 200.');
+ } catch (e) {
+ return (ok: false, detail: _describePingError(e));
+ }
+ }
+
+ /// Turn a raw ping exception into a plain-language reason. Classifies by
+ /// message text rather than type because the http package flattens socket
+ /// and TLS errors into ClientException, hiding the original class.
+ static String _describePingError(Object e) {
+ if (e is TimeoutException) {
+ return 'Timed out after 15s. The server is slow to respond, or something on the way is dropping the connection.';
+ }
+ final msg = e.toString();
+ final lower = msg.toLowerCase();
+ if (lower.contains('failed host lookup') || lower.contains('nodename nor servname')) {
+ return 'Could not resolve the domain (DNS). Check the address is spelled right. ($msg)';
+ }
+ if (lower.contains('handshake') || lower.contains('certificate') || lower.contains('tls')) {
+ return 'Secure connection (TLS) failed. If your server uses a self-signed certificate, turn on Trust all certificates above. Otherwise the server may be blocking non-browser apps. ($msg)';
+ }
+ if (lower.contains('connection refused')) {
+ return 'Connection refused - nothing is listening on that address or port. ($msg)';
+ }
+ if (lower.contains('connection closed before full header') ||
+ lower.contains('http/2') ||
+ lower.contains('protocol error')) {
+ return 'The server closed the connection early. This can happen when a proxy only speaks HTTP/2. ($msg)';
+ }
+ if (lower.contains('connection reset') || lower.contains('connection terminated')) {
+ return 'The connection was reset, which usually means a proxy or firewall is blocking the app even though browsers get through. ($msg)';
+ }
+ return msg;
+ }
+
/// Get the server version via the /status endpoint (no auth needed).
static Future<String?> getServerVersion(String serverUrl, {Map<String, String> customHeaders = const {}}) async {
final url = serverUrl.endsWith('/')