diff --git a/main.go b/main.go
index e5fe0d0..6da0847 100644
--- a/main.go
+++ b/main.go
@@ -243,7 +243,7 @@ func (c *KVSClient) handlePut(args []string) {
 	// Parse JSON data
 	var data json.RawMessage
 	if err := json.Unmarshal([]byte(args[1]), &data); err != nil {
-		fmt.Println(red("Invalid JSON:"), err)
+		printJSONError(args[1], err)
 		return
 	}
 
@@ -390,6 +390,40 @@ func (c *KVSClient) handleUserGet(args []string) {
 	fmt.Printf("  Updated:       %s\n", time.Unix(user.UpdatedAt, 0).Format(time.RFC3339))
 }
 
+// printJSONError displays a user-friendly JSON parsing error with helpful hints
+func printJSONError(input string, err error) {
+	fmt.Println(red("❌ Invalid JSON:"), err)
+	fmt.Println()
+
+	// Show what was received
+	if len(input) > 100 {
+		fmt.Println(yellow("Received:"), input[:100]+"...")
+	} else {
+		fmt.Println(yellow("Received:"), input)
+	}
+	fmt.Println()
+
+	// Provide helpful hints based on common errors
+	errMsg := err.Error()
+
+	if strings.Contains(errMsg, "looking for beginning of") ||
+	   strings.Contains(errMsg, "invalid character") {
+		fmt.Println(cyan("💡 Tip:"), "JSON with spaces needs quotes:")
+		fmt.Println(green("  ✓ Correct:"), "put key '{\"hello\":\"world\"}'")
+		fmt.Println(green("  ✓ Correct:"), "put key '{\"a\":1,\"b\":2}'")
+		fmt.Println(green("  ✓ Compact:"), "put key {\"a\":1,\"b\":2}  (no spaces)")
+		fmt.Println(red("  ✗ Wrong:  "), "put key {\"a\": 1, \"b\": 2}  (spaces without quotes)")
+	} else if strings.Contains(errMsg, "unexpected end of JSON") {
+		fmt.Println(cyan("💡 Tip:"), "JSON appears incomplete or cut off")
+		fmt.Println(green("  Check:"), "Are all brackets/braces matched? {}, []")
+		fmt.Println(green("  Check:"), "Did spaces split your JSON into multiple arguments?")
+	} else {
+		fmt.Println(cyan("💡 Tip:"), "Wrap JSON in quotes for complex values:")
+		fmt.Println(green("  Single quotes:"), "put key '{\"your\":\"json\"}'")
+		fmt.Println(green("  Double quotes:"), "put key \"{\\\"your\\\":\\\"json\\\"}\"")
+	}
+}
+
 func (c *KVSClient) handleHelp(args []string) {
 	help := `
 KVS Interactive Shell - Available Commands: