FAQ

A. AIOZ AI FAQ, Troubleshooting

A summary of common issues encountered when using AIOZ AI, and step-by-step guidance on how to resolve each one.

1. Git LFS (Large File Storage) errors

Error 1: Push/Fetch Timeout

Symptoms:

git push or git pull fails with error messages like i/o timeout, EOF, or Connection timed out. This usually happens on slow or unstable networks.

Cause:

The connection is cut before the large file transfer completes. The default LFS timeout is often only 30 seconds.

Fix:

• Increase the LFS timeout to 120 seconds (or higher):

  git config --global lfs.activitytimeout 120

• If the network is very poor, increase to 300 seconds (5 minutes):

  git config --global lfs.activitytimeout 300

• Then retry push / pull after setting the configuration.

Error 2: File exceeds 8GB limit

Symptoms:

Error message appears:

[...] Size must be less than or equal to 8589934592: [422] Size must be less than or equal to 8589934592

Cause:

You are trying to push a single file larger than the maximum allowed size (8GB).

Fix:

• Double-check the file — make sure it's not an accidental export or log file.
• Split the file into smaller parts, each under 8GB.
• If splitting is not possible, contact support.
  • Email: [email protected]
  • Subject: Git LFS Troubleshooting Request - [Your Repo Name]

Error 3: Large file appears as small pointer (~130 bytes)

Symptoms:

After clone or pull, large files (e.g., model.pth) are just small text files with content like:

version https://git-lfs.github.com/spec/v1
oid sha256:4d7a2146...
size 123456789

Cause:

Git LFS is not installed on your machine, or not initialized properly before cloning.

Fix:

• Install Git LFS from: https://git-lfs.com/ (opens in a new tab)

  • macOS: brew install git-lfs
  • Ubuntu/Debian: apt-get install git-lfs

• Initialize LFS (only once per machine):

  git lfs install

• Fetch actual files from LFS store:

  git lfs pull

2. SSH and repository connection errors

Error 4: Permission denied (publickey)

Symptoms:

When running git push or git clone via SSH, the error appears: Permission denied (publickey).

Cause:

• SSH key has not been added to your AIOZ AI account.
• SSH key has not been loaded into the SSH agent.
• Using HTTPS URL instead of SSH URL.

Fix:

• Check if your SSH key has been added to your account: go to Settings > SSH Keys.

• Add key to SSH agent:

  eval "$(ssh-agent -s)"
  ssh-add ~/.ssh/id_ed25519

• Verify you're using the correct SSH URL (not HTTPS):

  # View current remote
  git remote -v
  # If HTTPS, switch to SSH:
  git remote set-url origin [email protected]:<username>/<repo>.git

• Test SSH connection:

  ssh -T [email protected]

  Expected response:

  Hi username! You've successfully authenticated, but AIOZ AI Git does not provide shell access.

Error 5: Incorrect key permissions (Linux/MacOS)

Symptoms:

SSH shows the error WARNING: UNPROTECTED PRIVATE KEY FILE! and refuses to connect.

Cause:

The SSH key file has overly broad access permissions (e.g., 644 or 777 instead of 600).

Fix:

• Reset the correct permissions for SSH files:

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/id_ed25519
  chmod 644 ~/.ssh/id_ed25519.pub

Detailed SSH debugging:

• Add the -v flag to view detailed connection logs:

  ssh -vT [email protected]

3. Errors related to modeling and inference

Error 6: Model weights not found

Symptoms:

The model runs but reports an error that it cannot load the weights file, or raises FileNotFoundError during inference.

Causes:

• The path to the weights is hardcoded incorrectly.
• Not using the model_storage_directory variable provided by the adapter.
• The weights file has not been placed in the /models directory.

Fix:

Always use the model_storage_directory variable to access weights:

import os
import torch
 
def do_ai_task(input_image, example_param, model_storage_directory, device="cpu", *args, **kwargs):
    weights_path = os.path.join(model_storage_directory, "model.pth")
    model.load_state_dict(torch.load(weights_path, map_location=device))

• Ensure the weights file is located in the /models directory of the project.
• Use os.path.join() instead of string concatenation for cross-platform compatibility.

Error 7: Incorrect input/output structure

Symptoms:

The model fails when receiving input or returning output in the wrong format, leading to validation errors from the platform.

Cause:

The input and output classes do not inherit from the schemas the adapter library expects, so the platform cannot validate them.

Fix:

Inherit the correct InputObject and OutputObject classes from the adapter library:

from aioz_ainode_adapter.schemas import InputObject, OutputObject, FileObject
from typing import Optional, Any
 
class MyInput(InputObject):
    input_image: str
    example_param: Optional[Any] = ""
 
class MyOutput(OutputObject):
    text: str
    output_image: FileObject

• Provide default values for optional fields to avoid null errors.
• Carefully check data types (str, int, float, FileObject) for each field.

4. Dataset-related errors

Error 8: Upload dataset failure due to large file

Symptoms:

Pushing the dataset with git push fails with timeout or file size exceeded errors.

Cause:

Large datasets (several GBs) must be managed via Git LFS. They cannot be pushed directly with standard Git.

Fix:

• Ensure Git LFS is installed and initialized.

• Track common dataset file formats before adding:

  git lfs track "*.csv"
  git lfs track "*.zip"
  git lfs track "*.tar.gz"
  git lfs track "*.parquet"
  git lfs track "*.h5"

• Stage .gitattributes together with your data, then commit:

  git add .gitattributes
  git add data/
  git commit -m "Add dataset files"
  git push

Error 9: Dataset not visible to other users

Symptoms:

Dataset upload completes, but others cannot find it or download it.

Cause:

The dataset is set to Private, not Public.

Fix:

• Go to Dataset > Edit > Change Access to Public if you want to share with the community.
• After changing the setting, confirm to save your changes.

5. Account and payment errors

Error 10: Cannot submit - daily limit reached

Symptoms:

The submit button is disabled or a message appears saying the daily submission limit has been reached.

Fix:

• Check remaining submission attempts in the Rules tab of the Challenge.
• Wait until the next day when the limit resets.
• Plan submissions wisely: avoid "quick testing" too many times, verify locally first.

Error 11: Insufficient balance to unlock model/dataset

Symptoms:

When clicking Unlock Model, a warning appears about insufficient balance and the action cannot proceed.

Cause:

Your AIOZ AI account does not have enough AIOZ Tokens to pay the unlock fee.

Fix:

• Go to Balances & Transactions > Balances to check your current balance.
• Add more AIOZ Tokens via Add AIOZ Token.
• Note: Verify that the price shown on the model page matches the price in the Unlock popup before confirming.

Error 12: Wallet not connected

Symptoms:

Unable to connect the blockchain wallet to AIOZ AI.

Fix:

• Go to Balances & Transactions, then select the Connect wallet button.
• Make sure the wallet supports AIOZ Network (check under Add AIOZ Token).
• If the issue persists, contact us at [email protected].

B. AI Challenge Tips

1. Smart preparation and starting strong

Tip 1: Read all challenge information carefully first

Before submitting anything, go through all the tabs:

• Overview - Understand the goals and the problem to solve.
• Data - Read dataset descriptions, file structures, and download them for analysis.
• Code (Baseline) - Use the sample code provided; it's an important starting point.
• Discussion - Q&A forum with hints and clarifications from other participants and admins.
• Leaderboard - Public and private rankings, sorted by the challenge metric.
• Rules - Check submission limits per day, submission types, participation conditions, and evaluation rules.
• Timeline Bar - Pay attention to the registration deadline and the date the private leaderboard is announced.

Tip 2: Use filters to choose the right challenge

Use the filtering feature on the Challenges page to narrow down the list:

• By Category - Featured, Research, Getting Started, Community. Getting Started challenges are the most beginner-friendly.
• By Status - Active, Entered, Completed, Spotlight. Active challenges are the ones you can submit to right away; Entered are the ones you have already joined.
• By Prizes & Awards - Knowledge, Swag, Kudos, Monetary. Knowledge rewards are knowledge and experience, good for learning; Monetary rewards are real AIOZ Tokens and tend to be more competitive.

Tip 3: Join early

Once you join a challenge, the Submission tab will appear. Be sure to:

• Join as soon as the challenge opens - do not wait until the deadline.
• Download the dataset early and start with EDA (Exploratory Data Analysis).
• Submit a simple baseline model at the beginning to test your pipeline.

2. Preparing your submission properly

Tip 4: Public submission - CSV must be in the correct format

This is the most common type of submission (uploading a CSV file, the system auto-scores it):

• The first column must be id (unique identifier).
• The remaining columns are your predictions, and they must match the ground truth format.
• Double-check the number of rows: it must cover the entire test set, no missing or extra rows.

Tip 5: Private submission - Checklist before submitting

For Private submission (submit Model_ID), you need to prepare:

• Trained weights - Trained model weight file, placed in /models
• Model code - Fully implement do_ai_task() in my_ai_lib/run.py
• Inference script - predict_submission() in my_ai_lib/predict_submission.py
• Model public - Model must be set to public before submission.

Tip 6: Verify locally before submitting

Check that your solution runs correctly before wasting a submission attempt:

• Create a main() function in my_ai_lib/predict_submission.py
• Call predict_submission() inside main()
• Run local test: python -m my_ai_lib.predict_submission
• Check that the generated result.csv has the correct format.
• Compare the first few rows with the sample submission CSV from the challenge.

Tip 7: Understand the project structure

The standard structure of a submission project:

repository/
├── aioz_ainode_adapter/         # Platform adapter (provided)
├── my_ai_lib/                   # Your AI library
│   ├── __init__.py              # Required: library initialization
│   ├── run.py                   # Required: main workflow function
│   ├── predict_submission.py    # Required: submission function
│   └── [your_modules]/          # Your custom modules
├── models/                      # Model weights directory
├── wiki/                        # Assets used by the demo
├── demo.py                      # Demo script
├── compress.py                  # Packaging helper
└── setup.py                     # Package setup

3. Understanding the leaderboard and optimizing your score

Tip 8: Know which metric matters for your challenge

Each challenge uses different evaluation metrics. Check them right from the start:

• Classification - Accuracy, F1, ROC AUC → higher is better
• Classification - Log Loss, Brier Score → lower is better
• Regression - R2 Score → higher is better
• Regression - RMSE, MAE, MSE → lower is better
• Clustering - Adjusted Rand Score, Completeness Score → higher is better

Check more here: Understanding the Challenges

Tip 9: Public vs. Private leaderboard

• Public leaderboard: Updates in real time, showing your best current score.
• Private leaderboard: Revealed only after the challenge ends, using a hidden test set.

Tip 10: Track submission status

Each submission will have one of these statuses:

• ⏳ Pending - Being processed - wait for results, don't submit more yet.
• ✅ Success - Valid submission, score updated on the leaderboard.
• ❌ Failed - Error - check CSV format or model code, fix and resubmit.

4. Advanced tips and strategies

Tip 11: Make use of the Discussion tab

• Read the entire discussion thread before starting - it often contains important hints and clarifications.
• Ask questions if you do not understand the data format or challenge requirements.
• Share insights (not your full solution) to build reputation and expand your network.

Tip 12: Baseline code is your golden starting point

The Code tab in each challenge usually provides baseline code. Be sure to:

• Run the baseline successfully before making improvements.
• Understand the baseline's data pipeline thoroughly.
• Gradually replace or improve parts step-by-step: feature engineering → model → hyperparameter tuning.

Tip 13: Manage submission timing wisely

Do not use up all your submission attempts too early! Save at least 1-2 attempts for the final days when you have your best solution.

Suggested strategy:

• Days 1 - 3: Submit the baseline to understand the scoring system.
• Following days: Improve your model, submit only when you have meaningful improvements.
• Last 2 days: Focus on ensemble/final tuning, submit your best version.

Tip 14: Prizes & Awards - Understand to stay motivated

Types of rewards in the AIOZ AI Challenge:

• Knowledge - Skill certificates, great for building your portfolio
• Swag - Gifts from AIOZ (merchandise, etc.)
• Kudos - Reputation points in the AIOZ AI community
• Medals - Gold/Silver/Bronze medals for top participants
• Monetary - Real AIOZ Token rewards

Tip 15: Private submission - the model must be on AIOZ AI

C. Quick Reference

1. Git LFS Checklist

2. SSH Checklist

3. Private Submission Checklist

4. Contact Support