diff --git a/__tests__/docker.test.ts b/__tests__/docker.test.ts
index 99cd6ef..aaeb235 100644
--- a/__tests__/docker.test.ts
+++ b/__tests__/docker.test.ts
@@ -2,6 +2,7 @@ import {expect, jest, test} from '@jest/globals';
 import * as path from 'path';
 
 import {loginStandard, logout} from '../src/docker';
+import * as core from '@actions/core';
 
 import {Docker} from '@docker/actions-toolkit/lib/docker/docker';
 
@@ -37,6 +38,50 @@ test('loginStandard calls exec', async () => {
   });
 });
 
+test('loginStandard throws plain error on auth failure', async () => {
+  jest.spyOn(Docker, 'getExecOutput').mockImplementation(async () => {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Error response from daemon: unauthorized: incorrect username or password'
+    };
+  });
+
+  await expect(loginStandard('https://ghcr.io', 'user', 'wrongpass')).rejects.toThrow(
+    'Error response from daemon: unauthorized: incorrect username or password'
+  );
+});
+
+test('loginStandard appends network hint on timeout error', async () => {
+  jest.spyOn(Docker, 'getExecOutput').mockImplementation(async () => {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Error response from daemon: Get "https://ghcr.io/v2/": context deadline exceeded (Client.Timeout exceeded while awaiting headers)'
+    };
+  });
+  jest.spyOn(core, 'warning').mockImplementation(() => undefined);
+
+  await expect(loginStandard('https://ghcr.io', 'user', 'pass')).rejects.toThrow(
+    /context deadline exceeded[\s\S]*Hint: looks like a network connectivity issue/
+  );
+});
+
+test('loginStandard appends network hint on dial tcp error', async () => {
+  jest.spyOn(Docker, 'getExecOutput').mockImplementation(async () => {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Error response from daemon: Get "https://ghcr.io/v2/": dial tcp 140.82.112.21:443: i/o timeout'
+    };
+  });
+  jest.spyOn(core, 'warning').mockImplementation(() => undefined);
+
+  await expect(loginStandard('https://ghcr.io', 'user', 'pass')).rejects.toThrow(
+    /dial tcp[\s\S]*Hint: looks like a network connectivity issue/
+  );
+});
+
 test('logout calls exec', async () => {
   // eslint-disable-next-line @typescript-eslint/ban-ts-comment
   // @ts-ignore
diff --git a/src/docker.ts b/src/docker.ts
index fcb057b..52a4862 100644
--- a/src/docker.ts
+++ b/src/docker.ts
@@ -74,8 +74,22 @@ async function loginExec(registry: string, username: string, password: string, s
     env: envs
   }).then(res => {
     if (res.stderr.length > 0 && res.exitCode != 0) {
-      throw new Error(res.stderr.trim());
+      const errMsg = res.stderr.trim();
+      // if the docker daemon cannot reach the registry at all, user should get a more useful hint
+      // rather than just forwarding the raw timeout/dial error
+      if (isNetworkError(errMsg)) {
+        throw new Error(
+          `${errMsg}\n\nHint: looks like a network connectivity issue - verify the runner can reach ${registry} (check firewall rules, proxy settings, and DNS resolution).`
+        );
+      }
+      throw new Error(errMsg);
     }
     core.info('Login Succeeded!');
   });
 }
+
+// checks if a docker daemon error msg looks like a connectivity/timeout problem
+// vs an actual auth failure or other non-network error
+function isNetworkError(msg: string): boolean {
+  return /context deadline exceeded|request canceled|i\/o timeout|dial tcp|connection refused|no such host/.test(msg);
+}