diff --git a/.env.example b/.env.example
index e6f433a8..4b8f89e4 100644
--- a/.env.example
+++ b/.env.example
@@ -28,12 +28,14 @@ S3_ENDPOINT=
 S3_ACCESS_KEY_ID=
 S3_SECRET_ACCESS_KEY=
 S3_FORCE_PATH_STYLE=
+# S3_AVATAR_UPLOAD_LIMIT=2097152 # Avatar upload size limit in bytes (default: 2MB)
 NEXT_PUBLIC_STORAGE_URL=
 NEXT_PUBLIC_AVATAR_BUCKET_NAME=
 NEXT_PUBLIC_ATTACHMENTS_BUCKET_NAME=
 NEXT_PUBLIC_STORAGE_DOMAIN=
 NEXT_PUBLIC_USE_VIRTUAL_HOSTED_URLS=
 
+
 # Auth config (optional)
 NEXT_PUBLIC_ALLOW_CREDENTIALS=
 NEXT_PUBLIC_DISABLE_SIGN_UP=
diff --git a/README.md b/README.md
index dc7afb22..12c987d0 100644
--- a/README.md
+++ b/README.md
@@ -203,6 +203,7 @@ pnpm dev
 | `S3_ACCESS_KEY_ID`                        | S3 access key                                             | For file uploads (optional with IRSA) | `xxx`                                                       |
 | `S3_SECRET_ACCESS_KEY`                    | S3 secret key                                             | For file uploads (optional with IRSA) | `xxx`                                                       |
 | `S3_FORCE_PATH_STYLE`                     | Use path-style URLs for S3                                | For file uploads                      | `true`                                                      |
+| `S3_AVATAR_UPLOAD_LIMIT`                  | Maximum avatar file size in bytes                         | For file uploads                      | `2097152` (2MB)                                             |
 | `NEXT_PUBLIC_STORAGE_URL`                 | Storage service URL                                       | For file uploads                      | `https://storage.kanbn.com`                                 |
 | `NEXT_PUBLIC_STORAGE_DOMAIN`              | Storage domain name                                       | For file uploads                      | `kanbn.com`                                                 |
 | `NEXT_PUBLIC_USE_VIRTUAL_HOSTED_URLS`     | Use virtual-hosted style URLs (bucket.domain.com)         | For file uploads (optional)           | `true`                                                      |
diff --git a/apps/web/src/pages/api/upload/avatar.ts b/apps/web/src/pages/api/upload/avatar.ts
index de3508bf..8f5f996a 100644
--- a/apps/web/src/pages/api/upload/avatar.ts
+++ b/apps/web/src/pages/api/upload/avatar.ts
@@ -8,7 +8,7 @@ import { env } from "~/env";
 import { withRateLimit } from "@kan/api/utils/rateLimit";
 import { createS3Client } from "@kan/shared/utils";
 
-const MAX_SIZE_BYTES = 2 * 1024 * 1024; // 2MB
+const MAX_SIZE_BYTES = parseInt(process.env.S3_AVATAR_UPLOAD_LIMIT || '2097152', 10); // Default 2MB
 const allowedContentTypes = ["image/jpeg", "image/png", "image/webp"];
 
 export const config = {